Integração Payments
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.- 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. - Cancelar Invoice —
POST /payments/invoices/{id}/cancel(anula cobrança não paga) — em breve. - 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.
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 decustomer.country e currency. Você não precisa escolher.
Como Funciona
- 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). - 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.
- (Opcional) Um documento fiscal é anexado. Quando
currency = BRLetax_document.auto_issue: true, o SalesOS emite uma NFS-e automaticamente após a cobrança ser confirmada como paga. Você também pode chamarPOST /invoices/{id}/tax-documentsmais tarde para emitir ou tentar de novo. - 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 Resposta (201 Created):Status passa por
tax_document instrui o SalesOS a emitir a NFS-e automaticamente após a cobrança ser paga.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 Sem bloco
501 provider_not_configured.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 headerAuthorization:
Ambientes
- Production
- Staging
URL Base:
https://api.play2sell.comDashboard: https://dashboard.play2sell.comReferê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
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)
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 usarauto_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.
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
cancellation_window_expired é retornado quando fora da janela.
Campos de Controle Comuns
Toda Invoice carrega os mesmos campos de controle. Eles fazem round-trip emGET 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 endpointsPOST 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:400 — bad_request
400 — bad_request
JSON malformado ou headers obrigatórios ausentes. Corrija a requisição e reenvie.
403 — insufficient_scope
403 — insufficient_scope
Chave válida mas sem o escopo necessário (
payments:write ou payments:read). Edite a chave no Dashboard.404 — not_found
404 — not_found
O ID do recurso não existe ou pertence a outro tenant.
409 — idempotency_key_reused
409 — idempotency_key_reused
Mesma
Idempotency-Key usada com body diferente. Use uma chave nova ou envie o body original.422 — validation_error e relacionados
422 — validation_error e relacionados
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 arrayerrors[]lista os problemas a nível de campo. Corrija os dados e reenvie comIdempotency-Keynova.unsupported_region— a combinaçãocountry/currencydo cliente ainda não está disponível (hoje apenasBR/BRLestá ativo). Aguarde a região ser liberada ou cobre um cliente em uma região suportada.unknown_cost_center— o códigocost_centerenviado 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.
429 — rate_limited
429 — rate_limited
Muitas requisições. O header
Retry-After indica quantos segundos aguardar.502 — provider_error
502 — provider_error
O backend downstream retornou erro. O campo
detail contém uma mensagem sanitizada. Reenvie com a mesma Idempotency-Key.500 — server_error
500 — server_error
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.
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.
Roteamento por região
O SalesOS roteia automaticamente porcustomer.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 verifiqueX-Pay-Signature e dedupe por X-Pay-Delivery.
Tratamento de falhas
- 422: corrija os dados e reenvie com
Idempotency-Keynova. - 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.
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

