Saltar para o conteúdo principal

Integração Payments

Teste requisições assinadas no navegador no Sandbox da API — cole sua API key e secret, e o playground assina as requisições automaticamente.
Os exemplos abaixo mostram o header no formato wire Authorization: P2S-SIGN-V1 API_KEY:TIMESTAMP:SIGNATURE. Para computar a assinatura no seu código, use o helper signedRequest em Autenticação.
A integração Payments é uma API REST agnóstica de provedor para as operações financeiras essenciais que todo backoffice precisa:
  1. Emitir Invoice (cobrança) — POST /payments/invoices. Uma Invoice aqui é uma cobrança — um pedido de pagamento coletado via PIX, boleto, cartão, ACH ou SEPA dependendo da região.
  2. Cancelar Invoice — POST /payments/invoices/{id}/cancel (anula cobrança não paga) — em breve.
  3. Emitir documento fiscal (NFS-e/NF-e/PEPPOL) — POST /payments/invoices/{id}/tax-documents. Opcional, específico por região (Brasil hoje, Europa depois). Pode também ser auto-emitido na criação da Invoice.
Conteúdo restrito. Pagamento a beneficiários e extrato da conta estão disponíveis apenas para clientes com contrato comercial com a Play2sell. A documentação é compartilhada de forma privada após a assinatura do contrato — fale com seu gerente de conta ou com suporte@play2sell.com.
Toda transação carrega campos de controle de primeira classe usados pelo seu time financeiro para reconciliação: cost_center (centro de custos) e contractor_reference (número do contratante) você envia no request; our_number (nosso número) é gerado pelo SalesOS e devolvido no response. Por baixo, o SalesOS roteia a requisição para o provedor certo — você não precisa escolher provedor a menos que queira.
Cobrança ≠ documento fiscal. Uma Invoice é o pedido de pagamento (boleto, PIX, cartão). O documento fiscal (NFS-e no BR, PEPPOL na UE) é um recurso separado e opcional anexado à Invoice. Essa separação mantém a API portável entre BR / US / UE.
A API segue convenções de mercado: modelo REST por recurso, valores em unidades menores inteiras, timestamps ISO-8601, RFC 9457 Problem Details para erros, header Idempotency-Key para retry seguro, paginação por cursor e webhooks assinados. Se você já integrou com qualquer API moderna de pagamentos, vai se sentir em casa.

Roteamento por Região

O SalesOS escolhe o backend correto automaticamente a partir de customer.country e currency. Você não precisa escolher.

Como Funciona

  1. Você obtém uma Chave de API no Dashboard do SalesOS (Admin > Integrações > Chaves de API) com os escopos corretos (payments:write, payments:read).
  2. Você emite Invoices (cobranças). O SalesOS cria o pedido de pagamento na região do cliente (BR ativo; US/UE em breve). Você recebe um artefato pagável: QR-code/copia-e-cola PIX, código de barras de boleto, URL de checkout de cartão.
  3. (Opcional) Um documento fiscal é anexado. Quando currency = BRL e tax_document.auto_issue: true, o SalesOS emite uma NFS-e automaticamente após a cobrança ser confirmada como paga. Você também pode chamar POST /invoices/{id}/tax-documents mais tarde para emitir ou tentar de novo.
  4. Você escuta webhooks para eventos terminais (invoice.paid, invoice.canceled, tax_document.issued, …) em vez de fazer polling.

Início Rápido

1

Obtenha sua Chave de API

Vá até Admin > Integrações > Chaves de API no Dashboard do SalesOS. Crie uma nova chave com os escopos payments:write e payments:read. Copie a chave — ela só será exibida uma vez.Sua chave terá este formato: sk_live_a1b2c3d4e5f6g7h8i9j0...
2

Emita sua primeira Invoice (BR — cobrança PIX com NFS-e automática)

Crie uma cobrança PIX para um cliente brasileiro. O bloco opcional tax_document instrui o SalesOS a emitir a NFS-e automaticamente após a cobrança ser paga.
Resposta (201 Created):
Status passa por open → paid (na confirmação PIX, ~segundos) → tax_document.status: issued (emissão da NFS-e, segundos a minutos). Escute os webhooks invoice.paid e tax_document.issued em vez de fazer polling.
3

(Opcional) Emita uma Invoice para cliente US (em breve)

Para clientes US/UE o SalesOS roteia a cobrança para o backend internacional. Esse caminho está aguardando o onboarding da Play2Sell LLC — chamadas hoje retornam 501 provider_not_configured.
Sem bloco tax_document — US não possui documento fiscal nacional. Sales tax vai dentro de metadata ou de futuros line_items. O SSN do cliente não é coletado neste endpoint: cobranças B2C/B2B regulares nos EUA não exigem.

Autenticação

Todas as requisições exigem uma Chave de API no header Authorization:
Consulte a página de Autenticação para detalhes sobre como criar e gerenciar Chaves de API.

Ambientes

URL Base: https://api.play2sell.comDashboard: https://dashboard.play2sell.com

Referência de Endpoints

Path base: /functions/v1/payments. Todos os endpoints aceitam e retornam JSON.

Invoices (Cobranças)

Uma Invoice é uma cobrança — um pedido de pagamento que será coletado do seu cliente via PIX, boleto, cartão ou outro método dependendo da região. A Invoice não inclui um documento fiscal por padrão; veja Tax Documents abaixo.

POST /functions/v1/payments/invoices — criar uma cobrança

object
obrigatório
Cliente que será cobrado.
string
obrigatório
ISO-3166-1 alpha-2 (BR, US, DE, …). Decide o roteamento de provedor.
string
CPF (11 dígitos) ou CNPJ (14 dígitos) para BR (obrigatório quando tax_document está presente). Para cobranças US/UE este campo não é obrigatório — deixe de fora a menos que seu fluxo contábil precise. SSN/EIN não são coletados aqui em cobranças normais.
string
obrigatório
Razão social ou nome completo (max 255 caracteres).
string
obrigatório
Email válido — usado para recibos e (quando aplicável) entrega do documento fiscal.
string
Telefone opcional (max 20 caracteres). Formato E.164 recomendado (ex.: +5511999000111). Alguns provedores usam para correspondência AML/KYC e notificações transacionais.
integer
obrigatório
Valor total em unidades menores (ex: 12345 = R$ 123,45). Deve ser positivo.
string
obrigatório
Código ISO-4217. Decide o roteamento de provedor junto com customer.country.
string
obrigatório
Descrição que aparece no artefato de pagamento e (quando emitido) na discriminação do documento fiscal (max 1000 caracteres).
O campo description é exibido ao pagador. Em cobranças PIX aparece no app bancário/carteira do pagador junto ao QR-code; em boleto vai impresso no documento; em NFS-e entra na discriminação do serviço. Escolha um valor que faça sentido nos três contextos (ex: "Consultoria — Abril/2026", não "INV-2026-000123 linha-billing-interna").
object
obrigatório
Como a cobrança será coletada.
string
obrigatório
Um de pix, boleto, bolepix, card (BR); card, ach_debit, bank_transfer (US — em breve); card, sepa_debit, bank_transfer (UE — em breve).
integer
Para pix / boleto / bolepix: por quanto tempo o artefato de pagamento permanece válido. Padrão 3600 (PIX) / 3 dias (boleto).
string
Para card: para onde redirecionar o cliente após o checkout do cartão.
object
Opcional. Quando presente, o SalesOS emitirá um documento fiscal automaticamente após a cobrança ser paga. Hoje apenas BR.
boolean
Quando true, o documento fiscal é emitido no momento em que a cobrança transita para paid. Quando false (ou ausente), use POST /v1/invoices/{id}/tax-documents mais tarde.
string
"nfse" (serviços BR — ativo), "nfe" (produtos BR — em breve), "peppol" (UE — em breve).
string
Código municipal de serviço, obrigatório quando type="nfse" (ex: "01.05" para consultoria em SP).
string
Código do centro de custos interno (max 64 caracteres). Opcional — quando omitido, a cobrança é classificada no centro de custos padrão do tenant. Enviar um código não cadastrado retorna 422 unknown_cost_center. Veja Campos de Controle Comuns.
string
Número do contratante — referência externa do cliente/contrato (max 64 caracteres).
object
Pares chave-valor livres (max 50 chaves, valor max 500 caracteres).
our_number (nosso número) não vai no request — o SalesOS gera no momento da emissão e devolve no response (formato: INV-<AAAA>-<sequência>). Armazene para reconciliação.

GET /functions/v1/payments/invoices/{id} — consultar

A resposta sempre inclui o artefato corrente de payment_method (QR PIX, código de barras de boleto, URL de checkout de cartão) e o resumo inline de tax_document quando presente.

GET /functions/v1/payments/invoices — listar

Filtros: status (open|paid|canceled|failed), payment_method.type, cost_center, our_number, contractor_reference, created[gte], created[lte]. Paginação por cursor via limit (≤ 100), starting_after, ending_before.

POST /functions/v1/payments/invoices/{id}/cancel — anular cobrança não paga (em breve)

O cancelamento de Invoice pela API ainda não está disponível. Até lá, fale com o suporte para anular uma cobrança não paga.
Estorno de cobrança paga não está exposto na v1. Se você precisa reverter um pagamento já liquidado, fale com o suporte — o time pode processar manualmente. Uma versão futura da API pode expor um fluxo de estorno programático conforme os casos de uso amadurecerem.

Tax Documents (Documentos Fiscais)

Um TaxDocument é o artefato fiscal anexado a uma Invoice — hoje NFS-e (serviços BR). Tem ciclo de vida próprio e pode ser emitido, consultado ou cancelado independentemente da cobrança subjacente. Use este recurso quando você optou por não usar auto_issue na criação da Invoice, quando uma tentativa de auto-emissão falhou e você quer retentar, ou quando precisa cancelar apenas o documento fiscal.

POST /functions/v1/payments/invoices/{id}/tax-documents — emitir/retentar

string
obrigatório
"nfse" hoje. Futuro: "nfe", "peppol".
string
Obrigatório quando type="nfse".
object
Metadata livre opcional, persistido no documento.
Resposta (202 Accepted):
A emissão é assíncrona. Escute os webhooks tax_document.issued (ou tax_document.failed). Em sucesso o documento traz document_number, xml_url, pdf_url e issued_at.

GET /functions/v1/payments/invoices/{id}/tax-documents/{doc_id} — consultar

POST /functions/v1/payments/invoices/{id}/tax-documents/{doc_id}/cancel — cancelar

Sujeito à janela de cancelamento do município (tipicamente o dia da emissão para NFS-e). cancellation_window_expired é retornado quando fora da janela.

Campos de Controle Comuns

Toda Invoice carrega os mesmos campos de controle. Eles fazem round-trip em GET e são filtráveis em LIST.
Por que our_number é gerado no servidor. No banking brasileiro o cedente atribui o “nosso número” — mas nesta API o SalesOS é o gateway de emissão, então é o SalesOS que atribui o valor e devolve. Se você precisar carregar um identificador interno seu, use contractor_reference (top-level, indexado) ou metadata.* (livre).

Idempotência

Todos os endpoints POST exigem o header Idempotency-Key — uma string única à sua escolha (max 255 caracteres; recomendamos UUIDv4 ou uma chave determinística baseada no seu domínio).
  • A primeira chamada com a chave processa normalmente e a resposta é armazenada por 24 h.
  • Replays com a mesma chave e o mesmo body retornam a mesma resposta, com header Idempotent-Replay: true.
  • Replays com a mesma chave mas body diferente retornam 409 idempotency_key_reused.

Valores e Moeda

Valores são inteiros em unidades menores para evitar erros de ponto flutuante: Moedas seguem ISO-4217 (3 letras maiúsculas). Sempre pareie amount com currency. Rejeite no servidor qualquer payload que misture escalas (ex: enviar decimais).

Tratamento de Erros

Todos os erros seguem RFC 9457 Problem Details:
JSON malformado ou headers obrigatórios ausentes. Corrija a requisição e reenvie.
Chave de API ausente, inválida ou expirada. Verifique o header Authorization. Gere uma nova chave se expirada.
Chave válida mas sem o escopo necessário (payments:write ou payments:read). Edite a chave no Dashboard.
O ID do recurso não existe ou pertence a outro tenant.
Mesma Idempotency-Key usada com body diferente. Use uma chave nova ou envie o body original.
A requisição foi entendida mas não pode ser processada. Inspecione o campo code para desambiguar:
  • validation_error — validação do body falhou; o array errors[] lista os problemas a nível de campo. Corrija os dados e reenvie com Idempotency-Key nova.
  • unsupported_region — a combinação country / currency do cliente ainda não está disponível (hoje apenas BR / BRL está ativo). Aguarde a região ser liberada ou cobre um cliente em uma região suportada.
  • unknown_cost_center — o código cost_center enviado não está cadastrado para o seu tenant. Cadastre-o em Admin > Integrações > Centros de Custo antes de reenviar, ou omita o campo para usar o centro de custo padrão do tenant.
  • merchant_not_provisioned — o seu tenant não tem um merchant de pagamento ativo para o centro de custo resolvido. Contate o suporte para concluir o provisionamento antes de tentar novamente.
Muitas requisições. O header Retry-After indica quantos segundos aguardar.
O backend downstream retornou erro. O campo detail contém uma mensagem sanitizada. Reenvie com a mesma Idempotency-Key.
Erro interno. Reenvie com backoff exponencial (2s, 4s, 8s). Contate o suporte se persistir.

Webhooks

Configure um endpoint de webhook por ambiente em Admin > Integrações > Webhooks. O SalesOS fará POST com JSON assinado para todo evento terminal: Cada requisição inclui:
  • X-Pay-Event — tipo do evento (ex: invoice.paid).
  • X-Pay-Signature — t=<unix>,v1=<hex-hmac-sha256>. Verifique com o segredo configurado no Dashboard.
  • X-Pay-Delivery — ID único de entrega, útil para deduplicação.
Verificação de assinatura (Node.js):
Payload de exemplo:

Exemplos Completos de Código


Boas Práticas

Higiene de centros de custo

Escolha um conjunto pequeno e estável de códigos (≤ 50). Documente no wiki do financeiro. Rejeite no servidor chamadas que referenciem código desconhecido — falhar alto é melhor que classificar errado em silêncio.

Use as duas chaves juntas para reconciliação

  • our_number (gerado pelo servidor) é sua chave bancária — impressa no boleto / enviada ao provedor, presente no arquivo do extrato bancário.
  • contractor_reference (você fornece) é sua chave de contrato — o PO, ID do contrato com fornecedor ou ID do evento referente; presente no seu ERP.
Cruzar as duas no fechamento mensal entrega reconciliação de 1 clique entre o banco, a API Payments do SalesOS e seu ERP.

Roteamento por região

O SalesOS roteia automaticamente por customer.country e currency. Você não precisa escolher backend; confie no roteamento.

Confiabilidade dos webhooks

Trate webhooks como fonte de verdade para status terminal. Polling funciona mas consome rate limit. Sempre verifique X-Pay-Signature e dedupe por X-Pay-Delivery.

Tratamento de falhas

  • 422: corrija os dados e reenvie com Idempotency-Key nova.
  • 429: aguarde conforme Retry-After.
  • 502 (provider_error): reenvie com a mesma Idempotency-Key — a requisição original não foi commit, então retry é seguro.
  • 5xx: backoff exponencial (2s, 4s, 8s). Contate o suporte se persistir.

Limites de Requisições

Cada chave de API possui um limite configurável (padrão: 1000 requisições por hora). O contador reinicia a cada hora. Respostas com rate limit incluem o header Retry-After (segundos).

Segurança

  • Chaves de API são hasheadas com bcrypt — nunca armazenadas em texto puro.
  • Cada chave é restrita a um único tenant — sem acesso entre tenants.
  • Listas de IPs permitidos podem ser configuradas por chave.
  • Todas as requisições são registradas em log para auditoria (imutável, retenção de 7 anos).
  • As chaves podem ser revogadas instantaneamente pelo Dashboard.
Nunca exponha sua chave de API em código client-side (JavaScript no navegador, apps mobile ou repositórios públicos). A API Payments deve ser chamada apenas do seu servidor backend.

Próximos Passos

Autenticação

Saiba como criar e gerenciar Chaves de API

Integração Activities

Envie atividades do CRM para o SalesOS

Suporte

Precisa de ajuda? Entre em contato com nosso time de suporte