Versão v1 · base https://pagsim.com/api/v1
Toda chamada (menos GET /) precisa do cabeçalho:
Authorization: Bearer psk_...
A chave é gerada no painel: o titular do espaço, em Ajustes → Chave de API; quem é da equipe, no item Chave de API do menu. Ela vale para um espaço só e age como a pessoa que a criou: tudo que ela não pode fazer no painel, a chave também não faz — cada pessoa tem a sua, com as permissões que o titular marcou para ela em Ajustes → Equipe.
A chave para de funcionar sozinha, sem ninguém precisar revogá-la, quando a pessoa sai da equipe, quando a conta dela é suspensa, quando o espaço é arquivado, excluído ou fica com a assinatura vencida, e quando o plano do espaço deixa de incluir API. Os códigos de cada caso estão em Erros.
Comece pelo /me. Ele confirma a chave, mostra o espaço e lista as
permissões — numa chamada só, sem tocar em dado nenhum. Quem começa por
/receivables descobre três problemas possíveis ao mesmo tempo e não sabe qual é.
curl -H "Authorization: Bearer psk_..." \
https://pagsim.com/api/v1/me
{
"space": { "id": 12, "name": "Minha empresa", "currency": "BRL",
"timezone": "America/Sao_Paulo",
"invoice_host": "pagar.minhaempresa.com.br" },
"permissions": {
"receivables": 2, "payables": 1, "contacts": 2,
"files_rec": 2, "files_pay": 0, "files_contacts": 1,
"comment_rec": 2, "comment_pay": 0, "comment_contacts": 1,
"consumption_rec": 2, "consumption_pay": 0,
"nfse": 1,
"owner": false
},
"permission_levels": ["nenhum", "ver", "gerenciar"],
"features": { "payment_link": true, "attachments": true,
"contact_attachments": true, "custom_domain": true,
"nfse": true }
}
A chave age com as permissões da pessoa que a criou, e quem as marca é o titular do
espaço — não quem integra. Para não descobrir a falta de uma permissão num 403 em
produção, diga à API o que a sua integração usa e só siga com "ok": true:
curl -X POST https://pagsim.com/api/v1/permissions/check \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{
"permissions": { "receivables": "gerenciar", "contacts": "ver" },
"features": ["payment_link"]
}'
{ "ok": false, "missing": ["receivables"],
"message": "Falta: receivables (pede gerenciar; a chave tem ver). ..." }
Os detalhes, a forma de GET para script de deploy e os nomes aceitos estão em
POST /permissions/check, na lista de rotas.
15000 é R$ 150,00. Nunca decimais: devolver "150.00" convidaria
ao uso de float, e float em dinheiro é como um centavo some sem ninguém saber
onde. A moeda vai em cada recurso, porque nem toda moeda tem duas casas.
due_date, applied_on e afins são dias:
"2026-07-10". created_at, updated_at e
url_expires_at são instantes em UTC:
"2026-07-10T14:30:00Z". Misturar os dois faria o fuso do seu servidor mover
um vencimento de dia.
Dados úteis (a aba da conta onde ficam links, logins e senhas) e o texto dos comentários. Uma chave de API costuma viver em arquivo de configuração de servidor; essas duas coisas não deveriam estar ao alcance dela. Você pode escrever um comentário — anotar "baixa conferida pelo ERP" é útil e não expõe nada.
Também ficam só no painel: os relatórios, o pagamento pelo banco, o envio da
fatura por e-mail e a gravação dos campos personalizados (a API os lê em
custom_fields, mas ainda não os grava). Da nota fiscal, a API lista, lê,
baixa e pede a emissão; cancelar, a configuração (o sistema de nota, os dados
da empresa, de onde vem cada campo) e o certificado digital ficam no painel — são
decisões fiscais, e a tela é onde estão os avisos que elas pedem.
A nota fiscal (NFS-e) é pedida citando a conta a receber
(POST /receivables/{id}/nfse), sem dado nenhum no corpo. Ela é montada pela
configuração de nota fiscal do espaço — de onde vem cada campo, ligado pelo titular em
Ajustes → Nota fiscal — a partir da conta e do contato dela, pelo mesmo caminho do
botão "Emitir nota" do painel. Aceitar valores no pedido pularia essa configuração, e a nota
diria uma coisa enquanto a conta e o contato dizem outra.
Para mudar um valor da nota, mude antes a conta ou o contato
(PATCH /receivables/{id}, PATCH /contacts/{id}) e então peça a nota.
Um corpo com dados é recusado (422 corpo_nao_aceito), e não ignorado.
A emissão é assíncrona: a resposta é 202 com a nota na fila, e o
resultado chega pelo webhook (nfse.issued,
nfse.failed) ou em GET /nfse/{id}. Os detalhes estão em
"Nota fiscal (NFS-e)", na lista de rotas.
Content-Type: application/json em POST e PATCH. A única exceção é o envio
de anexo, que é multipart/form-data.
O PATCH é parcial de verdade: só os campos enviados mudam. Campo ausente significa "não mexi nisso", nunca "apague".
Cada rota traz o comando de exemplo e a resposta que ele devolve. Clique numa rota para abrir. Os valores são fictícios, mas a forma é exatamente a que a API retorna.
/
Nome e versão da API. Não exige chave — use para confirmar a URL.
Requisição
curl https://pagsim.com/api/v1/
Resposta
{
"name": "Pagsim API",
"version": "v1",
"docs": "https://pagsim.com/docs/api"
}
/me
O espaço da chave e AS PERMISSÕES dela. Comece por aqui.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/me
Resposta
{
"space": { "id": 12, "name": "Minha empresa", "currency": "BRL",
"timezone": "America/Sao_Paulo",
"invoice_host": "pagar.minhaempresa.com.br" },
"permissions": {
"receivables": 2, "payables": 1, "contacts": 2,
"files_rec": 2, "files_pay": 0, "files_contacts": 1,
"comment_rec": 2, "comment_pay": 0, "comment_contacts": 1,
"consumption_rec": 2, "consumption_pay": 0,
"nfse": 1,
"owner": false
},
"permission_levels": ["nenhum", "ver", "gerenciar"],
"features": { "payment_link": true, "attachments": true,
"contact_attachments": true, "custom_domain": true,
"nfse": true }
}
AS PERMISSÕES SÃO AS DO PAINEL, da pessoa que criou a chave — as mesmas
que o dono do espaço marcou para ela em Ajustes → Equipe. Cada rota abaixo
diz qual exige; sem ela, a resposta é 403 sem_permissao.
receivables / payables ver e gerenciar contas a receber / a pagar
contacts ver e gerenciar contatos
files_* anexos daquela área (ver/baixar · enviar/apagar —
apagar só os próprios, exceto o titular)
comment_* comentários daquela área (escrever exige 2)
consumption_* lançar itens de consumo naquela área (exige 2)
nfse nota fiscal: 1 lista, lê e baixa as notas;
2 pede a nota de uma conta (com receivables ver)
owner titular ou administrador: tudo
FEATURES diz o que o PLANO do espaço inclui entre o que a API oferece —
sem payment_link, POST .../payment-link responde 403 plano_nao_permite.
custom_domain é true quando os links da fatura saem no DOMÍNIO PRÓPRIO do
espaço (o plano inclui e o domínio já está ativo). nfse é a nota fiscal:
sem ela, toda rota de /nfse e POST /receivables/{id}/nfse respondem 403
plano_nao_permite — ler e baixar também.
INVOICE_HOST é o endereço em que os links da fatura deste espaço abrem
agora: o domínio próprio, quando custom_domain é true; senão, o da Pagsim.
Não monte o link com um endereço fixo no seu código — use o "invoice_url"
das contas, ou este host.
Para conferir de uma vez se a chave tem TUDO o que a sua integração usa,
veja POST /permissions/check, logo abaixo.
O TIMEZONE é o do espaço, e importa para quem compara datas.
As datas da API — due_date, happened_on, settled_at — são datas de
calendário, sem hora e sem fuso: "2026-09-10" é o dia 10, aqui e em
qualquer lugar. O fuso NÃO as desloca.
Ele importa para saber que dia é "hoje" para este espaço. O que decide se
uma conta está vencida, ou qual cobrança recebe um item novo, é o dia
corrente do espaço — não o do seu servidor. Um servidor em UTC às 22h de
São Paulo já virou o dia; usar a data dele faria uma conta parecer vencida
antes da hora.
Leia o timezone uma vez e calcule "hoje" com ele antes de comparar
qualquer due_date.
Os campos com HORA — created_at, updated_at, url_expires_at — vêm em UTC,
no formato ISO 8601 com Z no fim. Converta para exibir.
/permissions/check
Confere se a chave tem TUDO o que a sua integração usa. Rode antes de ir para produção.
Requisição
curl -X POST https://pagsim.com/api/v1/permissions/check \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{
"permissions": { "receivables": "gerenciar", "contacts": "ver", "files_rec": 2 },
"features": ["payment_link"]
}'
Resposta
{
"ok": false,
"space": { "id": 12, "name": "Minha empresa" },
"user": { "id": 7, "name": "Ana Souza" },
"permissions": [
{ "name": "receivables", "required": 2, "current": 1, "ok": false },
{ "name": "contacts", "required": 1, "current": 2, "ok": true },
{ "name": "files_rec", "required": 2, "current": 2, "ok": true }
],
"features": [
{ "name": "payment_link", "ok": true }
],
"missing": ["receivables"],
"message": "Falta: receivables (pede gerenciar; a chave tem ver). ..."
}
PARA QUE SERVE: diga o que a sua integração vai usar e receba um sim ou
não. Ponha esta chamada na partida do seu sistema, ou no deploy, e só
entre em produção com "ok": true. Sem ela, a chave errada só aparece como
403 no meio do caminho — no primeiro POST de verdade.
"ok" true só se a chave tem TODAS as permissões e recursos pedidos
"missing" os nomes do que falta (vazio quando ok)
"message" a mesma coisa em texto, dizendo quem resolve — para o seu log
ou para mostrar a quem configura a integração
"user" de quem são as permissões: a chave age como a pessoa que a
criou, e é para ela que o titular marca o que falta
A RESPOSTA É 200 SEMPRE QUE A CHAVE VALE — o resultado está em "ok", não
no código HTTP. Qualquer chave válida pode conferir as próprias
permissões. Chave inválida, revogada ou sem acesso ao espaço responde o
erro de sempre (401/403), o que também quer dizer "não está pronto".
O PEDIDO:
permissions os nomes do /me, com o nível mínimo de cada um:
1 ou "ver", 2 ou "gerenciar".
"owner": true exige que a chave seja do titular ou de um
administrador do espaço.
Os nomes curtos das rotas também valem: "rec" é
receivables, "pay" é payables.
features os recursos do plano que você usa — os de "features" do
/me: payment_link, attachments, contact_attachments,
custom_domain (os links da fatura saem no domínio próprio),
nfse (nota fiscal)
SEM NÍVEL, vale o menor que a API usa para aquela permissão: "ver" na
maioria; "gerenciar" em comment_* e consumption_*, que na API só servem
para escrever (não há rota que leia comentários, e para ler os itens de
uma conta basta ver a conta). Por isso "comment_rec": "ver" é recusado
(422 nivel_invalido) — nenhuma rota o aceitaria.
A ÁREA VAI JUNTO. Anexos, comentários e itens só existem dentro da área:
toda rota de files_rec está em /receivables, que antes exige receivables
(ver). Por isso pedir files_rec (ou comment_rec, consumption_rec) confere
também receivables, pelo menos "ver" — e o mesmo com payables e contacts.
Essa linha extra vem com "implied_by", dizendo quem a trouxe:
{ "name": "receivables", "required": 1, "current": 0, "ok": false,
"implied_by": ["files_rec"] }
"features" confere o PLANO; a permissão de quem usa o recurso vai em
"permissions". Para gerar link de pagamento, peça os dois:
payment_link e receivables: "gerenciar". Para enviar anexos:
attachments e files_rec (ou files_pay) "gerenciar"; em contatos,
contact_attachments e files_contacts "gerenciar".
NOTA FISCAL: "nfse": "ver" para listar, ler e baixar as notas;
"nfse": "gerenciar" para pedir a nota de uma conta. Duas coisas vêm
junto, e aparecem com "implied_by":
· o recurso nfse do plano — toda rota de nota fiscal o confere, até a
leitura; a permissão sem o recurso não serve para nada;
· com "gerenciar", também receivables (ver): a nota é sempre de uma
conta a receber, e o painel não deixa emitir quem não vê as contas.
{ "permissions": { "nfse": "gerenciar" } } →
"permissions": [
{ "name": "receivables", "required": 1, "current": 1, "ok": true,
"implied_by": ["nfse"] },
{ "name": "nfse", "required": 2, "current": 2, "ok": true } ],
"features": [ { "name": "nfse", "ok": true, "implied_by": ["nfse"] } ]
"nfse" é nome de permissão e de recurso: quando faltam os dois, aparece
uma vez só em "missing" — os itens de "permissions" e "features" dizem
qual falta.
Os dois aceitam lista ou objeto:
{ "permissions": ["receivables:gerenciar", "contacts"],
"features": ["payment_link"] }
{ "permissions": { "receivables": 2, "contacts": 1, "owner": true },
"features": { "payment_link": true } }
O mesmo nome mais de uma vez (ex.: "rec" e "receivables") vale pelo
MAIOR nível. Mas a mesma CHAVE repetida dentro de um objeto JSON é
recusada (422 chave_repetida): o JSON fica só com a última, e conferir um
nível que você não quis seria pior que dar erro.
NOME DESCONHECIDO É RECUSADO, nunca ignorado: um "recievables" digitado
errado não pode aprovar a chave. O mesmo vale para campo desconhecido no
corpo ou na query — um "permission" sem o s deixaria de conferir as
permissões. (É o contrário das listas, onde parâmetro desconhecido é
ignorado: lá ignorar só traz mais linhas; aqui aprovaria a chave.) A
resposta é 422 dados_invalidos, com "reason" e a lista do que é aceito:
{ "error": { "code": "dados_invalidos",
"message": "Permissão desconhecida: recievables. Use os nomes do /me.",
"field": "permissions",
"reason": "permissao_desconhecida",
"unknown": ["recievables"],
"accepted": ["receivables", "payables", "contacts", "..."] } }
"reason": permissao_desconhecida · recurso_desconhecido ·
campo_desconhecido · chave_repetida ·
nivel_invalido (ex.: 3, "talvez", ou "ver" em comment_*) ·
valor_invalido · formato · vazio (nada a conferir — uma
configuração esquecida em branco não pode passar como aprovada)
Se vier algo também na query (?permissions=...), SOMA ao corpo.
Só leitura: não muda nada e não exige escrita.
/permissions/check
A mesma conferência numa linha — para script de deploy.
Requisição
curl -G https://pagsim.com/api/v1/permissions/check \
-H "Authorization: Bearer psk_..." \
--data-urlencode "permissions=receivables:gerenciar,contacts:ver" \
--data-urlencode "features=payment_link"
Resposta
{ "ok": true, "missing": [], "message": "A chave tem tudo o que foi pedido.", ... }
Os mesmos campos do POST, separados por vírgula. Repetir o parâmetro
também vale e SOMA — ?permissions=receivables:gerenciar&permissions=contacts
confere os dois —, assim como ?permissions[]=contacts e
?permissions[receivables]=2. Parâmetro que não seja permissions ou
features é recusado (os que começam com _ são ignorados).
Para travar o deploy quando falta algo (o jq -e sai com erro quando "ok"
é false):
curl -s -G "https://pagsim.com/api/v1/permissions/check" \
-H "Authorization: Bearer $PAGSIM_KEY" \
--data-urlencode "permissions=receivables:gerenciar,contacts:ver" \
--data-urlencode "features=payment_link" \
| jq -e .ok > /dev/null || { echo "Chave da Pagsim sem as permissões necessárias"; exit 1; }
/receivables
rec (ver)
Lista, com filtros e paginação.
Requisição
curl -H "Authorization: Bearer psk_..." \
"https://pagsim.com/api/v1/receivables?status=pending&per_page=2"
Resposta
{
"data": [
{
"id": 1234,
"direction": "in",
"description": "Mensalidade de julho",
"amount": 15000,
"paid_amount": null,
"currency": "BRL",
"due_date": "2026-07-10",
"status": "pending",
"settled_at": null,
"category": { "id": 5, "name": "Serviços" },
"account": { "id": 2, "name": "Banco Inter" },
"contact": { "id": 88, "name": "Fulano" },
"party": null,
"has_items": false,
"invoice_code": "26-K7M2XQ",
"invoice_url": "https://pagar.minhaempresa.com.br/26-K7M2XQ",
"recurrence_id": null,
"created_at": "2026-06-28T11:02:00Z",
"updated_at": "2026-06-28T11:02:00Z",
"nfse": { "id": 55, "status": "emitida", "number": "1007" }
}
],
"meta": { "total": 137, "page": 1, "per_page": 2, "total_pages": 69 }
}
Filtros na seção "Filtros e paginação", mais abaixo. A busca "q" é a mesma
da tela: descrição e nome da outra parte sem diferença de acento ("agua"
acha "Água") e o número da fatura, inteiro ou só a parte depois do traço.
NFSE é o resumo da NOTA FISCAL da conta — id, situação e número oficial —,
a mesma nota que a tela da conta mostra: a que está viva (na fila,
enviada, emitida, em cancelamento, ou parada com erro depois de um envio
sem resposta) ou, sem nenhuma viva, a mais recente. Vem null quando a conta
não tem nota e também quando a chave não vê notas (sem a permissão nfse,
ou plano sem nota fiscal) — o resto da conta sai do mesmo jeito. A nota
inteira está em GET /nfse/{id}. O mesmo "nfse" volta em todas as rotas que
devolvem a conta (criar, alterar, baixar, reabrir, cancelar).
INVOICE_URL é o link da fatura para mandar ao cliente, JÁ NO DOMÍNIO
PRÓPRIO do espaço quando ele tem um ativo e o plano inclui domínio próprio
(o mesmo endereço do painel e do e-mail da fatura); senão, no endereço da
Pagsim. Vem null nos mesmos casos em que o painel não mostra o link: conta
a pagar, link ainda não gerado (ou revogado no painel) e plano sem link de
fatura. Não traz o pin — o pin sai só em
POST /receivables/{id}/payment-link, que também gera o link quando ele
ainda não existe.
/receivables/{id}
rec (ver)
Uma conta completa: itens, campos personalizados, correções e anexos.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/receivables/1234
Resposta
{
"id": 1234,
"direction": "in",
"description": "Mensalidade de julho",
"amount": 15000,
"currency": "BRL",
"due_date": "2026-07-10",
"status": "pending",
"invoice_code": "26-K7M2XQ",
"invoice_url": "https://pagar.minhaempresa.com.br/26-K7M2XQ",
"notes": "Combinado por telefone",
"custom_fields": [
{ "id": 3, "label": "Contrato", "type": "text", "value": "CT-2026-01" }
],
"items": null,
"corrections": [
{ "index": "IGPM", "percent": 0.42,
"amount_before": 14937, "amount_after": 15000, "applied_on": "2026-07-01" }
],
"attachments": [
{ "id": 77, "name": "nota.pdf", "size": 20481, "mime": "application/pdf",
"url": "https://s3.../nota.pdf?X-Amz-Signature=...",
"url_expires_at": "2026-08-16T15:05:00Z",
"created_at": "2026-07-02T09:14:00Z" }
],
"nfse": { "id": 55, "status": "emitida", "number": "1007" }
}
"nfse": o resumo da nota fiscal da conta, ou null — ver GET /receivables.
Para pedir a nota desta conta: POST /receivables/{id}/nfse, na seção
"Nota fiscal (NFS-e)".
/receivables
rec (gerenciar)
Cria uma conta. `direction` vem da rota e é ignorado no corpo.
Requisição
curl -X POST https://pagsim.com/api/v1/receivables \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{
"description": "Mensalidade de julho",
"amount": 15000,
"due_date": "2026-07-10",
"contact_id": 88,
"category_id": 5,
"account_id": 2
}'
Resposta
201 Created
{
"id": 1234,
"direction": "in",
"description": "Mensalidade de julho",
"amount": 15000,
"currency": "BRL",
"due_date": "2026-07-10",
"status": "pending",
"category": { "id": 5, "name": "Serviços" },
"contact": { "id": 88, "name": "Fulano" }
}
OS CAMPOS são os do formulário do painel:
description obrigatória
amount obrigatório, em centavos
due_date obrigatório, YYYY-MM-DD
category_id, account_id, contact_id opcionais — ids DESTE espaço
party nome da outra parte, em texto (quando não há contato)
notes observação
ruleset_id juros/multa/desconto (GET /rulesets) — SÓ a receber
index_id índice de correção (GET /indices) — SÓ a receber
settled true = a conta já nasce paga/recebida, na data do vencimento
has_consumption 1 = CONTA DE ITENS: exige também consumption_rec
(ou consumption_pay) gerenciar; nasce com valor 0 e sem
categoria — o valor passa a ser a soma dos itens (/items)
Um id de categoria, conta, contato, juros ou índice que não seja deste
espaço é recusado: 422 com "field" apontando o campo. Índice ARQUIVADO
também é recusado ao ligar uma conta a ele — a conta que já estava nele
continua aceitando as outras alterações. Numa conta a pagar,
ruleset_id e index_id são ignorados — juros de conta a pagar quem define é
o credor, e o painel faz o mesmo.
VINCULAR UM CONTATO (contact_id) exige também contacts (ver) — no painel,
quem não vê contatos não tem o seletor. Sem essa permissão a resposta é
403 sem_permissao; mandar o mesmo contato que a conta já tem, ou null para
desligar, continua valendo.
Erro de validação: 422 dados_invalidos com "field" (amount, due_date,
description, category_id... ou "quota", quando o limite de lançamentos do
plano para aquele mês acabou).
/receivables/{id}
rec (gerenciar)
Altera SÓ os campos enviados. O resto fica como está.
Requisição
curl -X PATCH https://pagsim.com/api/v1/receivables/1234 \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{ "amount": 18000 }'
Resposta
{
"id": 1234,
"description": "Mensalidade de julho",
"amount": 18000,
"due_date": "2026-07-10",
"status": "pending"
}
Aceita: description, amount, due_date, category_id, account_id, party,
contact_id, notes, ruleset_id e index_id (os dois últimos só a receber).
Trocar o contact_id por outro contato exige contacts (ver), como no POST.
A DIREÇÃO NÃO MUDA — nem no painel. Quem errou o lado apaga e cria de novo.
CONTA DE ITENS: amount e category_id não se alteram (o valor é a soma dos
itens e a categoria é de cada item). Mandá-los com um valor DIFERENTE do
atual responde 422 conta_de_itens; o mesmo valor de volta é aceito.
Numa conta já baixada, alterar o valor redefine o recebido — a mesma regra
da tela.
/receivables/{id}
rec (gerenciar)
Exclui SÓ esta conta — numa série, as outras parcelas ficam.
Requisição
curl -X DELETE https://pagsim.com/api/v1/receivables/1234 \
-H "Authorization: Bearer psk_..."
Resposta
{ "deleted": true, "id": 1234 }
/receivables/{id}/settle
rec (gerenciar)
Dá baixa. Corpo opcional.
Requisição
curl -X POST https://pagsim.com/api/v1/receivables/1234/settle \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{ "settled_at": "2026-07-09", "paid_amount": 15000 }'
Resposta
{
"id": 1234,
"amount": 15000,
"paid_amount": 15000,
"status": "received",
"settled_at": "2026-07-09"
}
settled_at opcional, YYYY-MM-DD. Sem ele, hoje — no fuso do espaço.
Data que não existe (2026-02-31) responde 422 data_invalida.
paid_amount opcional, em centavos. Sem ele, grava o valor DO DIA, já com
juros, multa e desconto das regras da conta — o mesmo número
que a tela de baixa mostra. Mande-o quando entrou outro valor
(pagamento parcial, negociação).
/receivables/{id}/unsettle
rec (gerenciar)
Reabre a conta.
Requisição
curl -X POST https://pagsim.com/api/v1/receivables/1234/unsettle \
-H "Authorization: Bearer psk_..."
Resposta
{ "id": 1234, "status": "pending", "paid_amount": null, "settled_at": null }
Se a conta foi paga ONLINE, vale a mesma decisão do /cancel: sem "refund"
no corpo, 409 exige_decisao_estorno; "refund": true devolve ao cliente e
reabre; "refund": false só reabre na Pagsim.
/receivables/{id}/cancel
rec (gerenciar)
Cancela. Se houver pagamento online, exige decidir sobre o estorno.
Requisição
curl -X POST https://pagsim.com/api/v1/receivables/1234/cancel \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{ "refund": true }'
Resposta
{ "id": 1234, "status": "cancelled",
"refund": { "amount": 15000, "external_id": "re_1abc" } }
Se a conta foi paga online e o corpo NÃO traz "refund", vem 409:
{ "code": "exige_decisao_estorno",
"payment": { "module": "stripe", "amount": 15000,
"currency": "BRL", "refundable": true } }
Aí escolha: "refund": true devolve ao cliente; false cancela só no
Pagsim. Não é automático porque devolver dinheiro é irreversível e a
tarifa normalmente não volta junto. Aceita "refund_amount" em centavos
para devolução parcial.
/receivables/{id}/payment-link
rec (gerenciar)
O link para o cliente pagar. Idempotente.
Requisição
curl -X POST https://pagsim.com/api/v1/receivables/1234/payment-link \
-H "Authorization: Bearer psk_..."
Resposta
201 Created
{ "code": "26-K7M2XQ",
"pin": "4821",
"url": "https://pagar.minhaempresa.com.br/26-K7M2XQ?code=4821",
"url_sem_pin": "https://pagar.minhaempresa.com.br/26-K7M2XQ" }
O ENDEREÇO é o do espaço: com domínio próprio ativo e o plano incluindo
domínio próprio, o link sai nele — o mesmo do painel e do e-mail da
fatura, e o mesmo "invoice_url" das contas; senão, sai no endereço da
Pagsim. É o "invoice_host" do /me.
A conta nasce com o número da fatura, mas SEM pin — o pin é credencial
de acesso e só existe quando alguém pede o link. Sem chamar esta rota, a
fatura pública recusa o visitante.
Chamar de novo devolve o MESMO código e pin: regerar invalidaria um link
que talvez já esteja com o cliente.
A rota também ATIVA o link público da conta (como o botão "gerar link" do
painel), se ele ainda não estiver ativo. Se alguém revogar o link pelo
painel, a URL para de abrir até esta rota ser chamada de novo.
url_sem_pin serve para mandar o link no e-mail e o pin por outro canal.
Só contas a receber (a pagar: 422 so_receivables), e só se o plano do
espaço incluir link de fatura (senão 403 plano_nao_permite — veja
"features" no /me). Conta cancelada: 422 conta_cancelada.
/payables…
pay
As MESMAS rotas de /receivables, trocando a permissão rec por pay (e files_rec por files_pay, comment_rec por comment_pay, consumption_rec por consumption_pay). Corpos e respostas idênticos, com "direction": "out". Diferenças: não há payment-link nem nota fiscal (sem o campo "nfse", e POST .../nfse responde 422 so_receivables), e ruleset_id/index_id são ignorados.
Requisição
curl -H "Authorization: Bearer psk_..." \
"https://pagsim.com/api/v1/payables?status=overdue"
Resposta
{
"data": [
{ "id": 991, "direction": "out", "description": "Aluguel da sala",
"amount": 80000, "currency": "BRL", "due_date": "2026-07-05",
"status": "overdue" }
],
"meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 }
}
/receivables/{id}/items
rec (ver)
Os itens da conta. Basta ver a conta — como no painel.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/receivables/1234/items
Resposta
{
"data": [
{ "id": 9, "description": "Hora técnica", "direction": "debit",
"unit_amount": 10000, "total": 10000,
"happened_on": "2026-07-03",
"category": { "id": 5, "name": "Serviços" },
"recurring": false,
"cancelled": false }
]
}
unit_amount e total são iguais nas linhas novas. Podem divergir em linhas
antigas, de quando o formulário ainda pedia quantidade. Use sempre o
"total": é o número que soma na conta, certo nos dois casos.
ITEM CANCELADO continua na lista, com "cancelled": true — é histórico, e o
painel mostra riscado —, mas NÃO entra no valor da conta. Some só os que
têm "cancelled": false. (O mesmo vale para "items" em GET /receivables/{id}.)
/receivables/{id}/items
consumption_rec (gerenciar)
Lança um item. Só em conta de itens e ainda aberta.
Requisição
curl -X POST https://pagsim.com/api/v1/receivables/1234/items \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{
"description": "Hora técnica",
"amount": 10000,
"category_id": 5
}'
Resposta
201 Created
{ "id": 9, "transaction_total": 25000 }
O item é: descrição, valor, categoria e data — os mesmos campos do
formulário do painel.
description obrigatória
amount obrigatório, em centavos, JÁ É O VALOR CHEIO da linha.
2 horas a R$ 50,00 → 10000, não 5000.
category_id obrigatória: sem ela o item não entra em relatório nenhum
happened_on opcional, YYYY-MM-DD. Sem ela, hoje.
Data inválida devolve 422, não vira hoje em silêncio.
direction debit (padrão) soma · credit abate
Não existe mais "qty": o painel deixou de pedir quantidade e a API
acompanhou. Mande o valor já multiplicado.
Recusas: 422 nao_foi_possivel, com "reason":
conta_sem_itens a conta é de valor fixo (criada sem has_consumption)
fechada paga, cancelada ou vencida — não recebe mais itens
sem_desc / valor / sem_cat com "field" apontando o campo
categoria_invalida category_id que não é deste espaço
/receivables/{id}/items/{itemId}
consumption_rec (gerenciar)
Remove um item.
Requisição
curl -X DELETE https://pagsim.com/api/v1/receivables/1234/items/9 \
-H "Authorization: Bearer psk_..."
Resposta
{ "deleted": true, "transaction_total": 15000 }
O item fica no histórico com "cancelled": true e sai da soma. Id que não é
desta conta: 404. Repetir a chamada num item já cancelado responde igual
(200) — o reenvio depois de uma queda de rede é seguro.
/recurrences
rec ou pay (ver)
Lista as réguas. Filtros: direction, external_ref, contact_id, active.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/recurrences?external_ref=boffice-4711
Resposta
{ "data": [ { "id": 77, "external_ref": "boffice-4711", "description": "Plano Pro",
"amount": 9900, "freq": "monthly", "active": true,
"itemized": false, "next_due_date": "2026-09-10" } ], "count": 1 }
A PERMISSÃO É A DO LADO DA RÉGUA, como no painel: régua a receber exige
rec, régua a pagar exige pay. A lista traz só os lados que a chave vê;
?direction=in|out filtra. Pelo id, uma régua do lado que a chave não vê
responde 404 — como se não existisse.
?active=true|false (ou 1|0) filtra as ligadas ou as desligadas. Até 200
réguas por chamada, das mais novas para as mais antigas.
/recurrences
rec ou pay (gerenciar)
Cria a régua e já gera as primeiras cobranças.
Requisição
curl -X POST https://pagsim.com/api/v1/recurrences \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{
"external_ref": "boffice-4711",
"description": "Plano Pro",
"amount": 9900,
"freq": "monthly",
"start_date": "2026-09-10",
"contact_id": 88,
"category_id": 5
}'
Resposta
201 Created
{ "id": 77, "external_ref": "boffice-4711", "amount": 9900,
"freq": "monthly", "active": true, "itemized": false,
"next_due_date": "2026-09-10" }
409 se a external_ref já existe — a resposta traz o recurrence_id de quem a tem.
ITENS JUNTO, numa transação só. Em série de itens ("has_consumption": 1),
o corpo aceita "items": [...] e a régua nasce com o plano dentro:
{ "description": "Assinatura", "amount": 0, "freq": "monthly",
"start_date": "2026-09-10", "contact_id": 88,
"has_consumption": 1,
"items": [ { "description": "Mensalidade Pro",
"amount": 9900, "category_id": 5 } ] }
Assim não há janela entre criar a régua e mandar o modelo — nessa fresta o
cron poderia passar e gerar uma cobrança vazia. Os modelos são gravados
ANTES da materialização, então já valem na primeira cobrança.
Item inválido recusa a chamada inteira: nenhuma régua é criada. Ou vale
tudo, ou não vale nada.
CAMPOS: description, amount (centavos), freq (weekly, biweekly, monthly,
quarterly, semiannual, annual), start_date, e opcionais end_date,
occurrences, contact_id, category_id, account_id, party, ruleset_id,
index_id, external_ref, has_consumption e items. O contact_id exige
contacts (ver), como nas contas.
direction: "in" (padrão, a receber) ou "out" (a pagar). Decide a
permissão: régua a pagar exige pay (gerenciar). Juros e índice só valem a
receber — numa régua a pagar são ignorados, como no painel.
Série de itens (has_consumption ou items) exige também consumption_rec
(ou consumption_pay) gerenciar — a mesma permissão que o painel pede.
Ids de contato, categoria, conta, juros ou índice que não sejam deste
espaço: 422 campo_invalido com "field".
/recurrences/{id}
rec ou pay (gerenciar)
Troca de plano. Só os campos enviados mudam.
Requisição
curl -X PATCH https://pagsim.com/api/v1/recurrences/77 \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{ "amount": 19900 }'
Resposta
{ "id": 77, "amount": 19900, "charges_updated": 6 }
charges_updated = quantas cobranças JÁ GERADAS receberam o valor novo.
O cron materializa ~190 dias à frente, então mexer só na régua faria o
plano novo valer daqui a meio ano. Vencidas e pagas ficam como estão.
effective_from (opcional, YYYY-MM-DD) muda o corte das cobranças alcançadas.
A DIREÇÃO NÃO MUDA depois de criada — "direction" no corpo é ignorado.
Trocar o contact_id por outro contato exige contacts (ver), como no POST.
/recurrences/{id}
rec ou pay (gerenciar)
Desliga a régua. As cobranças geradas continuam.
Requisição
curl -X DELETE https://pagsim.com/api/v1/recurrences/77 -H "Authorization: Bearer psk_..."
Resposta
{ "id": 77, "active": false }
Para remover também as cobranças pendentes, use /subscriptions/{id}/cancel.
Chamar de novo numa régua já desligada não faz nada — ela continua
desligada (reenviar depois de uma queda de rede é seguro). Para religar,
POST /subscriptions/{id}/reactivate.
/recurrences/{id}/items
rec ou pay (ver)
Os itens da próxima cobrança aberta.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/recurrences/78/items
Resposta
{ "data": [ ... ], "count": 3, "transaction_id": 4110,
"due_date": "2026-09-10", "total": 27500 }
/recurrences/{id}/items
consumption_rec ou _pay (gerenciar)
Lança um item na próxima cobrança aberta.
Requisição
curl -X POST https://pagsim.com/api/v1/recurrences/78/items \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{
"description": "Hora técnica",
"amount": 10000,
"category_id": 5
}'
Resposta
201 Created
{ "id": 9, "transaction_id": 4110, "due_date": "2026-09-10", "total": 27500 }
Campos: description, amount (centavos, valor cheio), category_id,
happened_on (opcional, YYYY-MM-DD) e direction (debit|credit).
Não há "qty" — mande o valor já multiplicado.
Se a cobrança do mês já fechou (paga, cancelada ou vencida), o item vai
para a SEGUINTE sozinho — por isso a resposta traz transaction_id e
due_date: é onde ele caiu de fato.
Sem cobrança aberta, 422 com um destes códigos:
sem_conta_aberta — série ativa, cron ainda não gerou. Tente depois.
serie_encerrada — série desligada ou vencida. Pare de enviar.
serie_sem_itens — régua de valor fixo; itens não têm onde entrar.
/recurrences/{id}/item-templates
rec ou pay (ver)
Os itens que se repetem em toda cobrança.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/recurrences/78/item-templates
Resposta
{ "data": [
{ "id": 4, "description": "Mensalidade Pro", "direction": "debit",
"amount": 9900, "category_id": 5,
"repeat_count": null, "repeats_done": 0, "repeats_left": null },
{ "id": 7, "description": "Notebook 6x", "direction": "debit",
"amount": 50000, "category_id": 5,
"repeat_count": 6, "repeats_done": 2, "repeats_left": 4 }
], "count": 2 }
repeat_count null = repete sempre. Um número = parcelado, e repeats_left
diz quantas faltam.
/recurrences/{id}/item-templates
consumption_rec ou _pay (gerenciar)
Cria um item recorrente e aplica às cobranças abertas.
Requisição
curl -X POST https://pagsim.com/api/v1/recurrences/78/item-templates \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{
"description": "Mensalidade Pro",
"amount": 9900,
"category_id": 5
}'
Resposta
201 Created
{ "id": 4, "description": "Mensalidade Pro", "amount": 9900,
"created": true, "charges_updated": 6 }
Corpo: description, amount (centavos), category_id, direction (debit|credit)
e repeat_count (opcional).
NÃO tem happened_on — um modelo não tem data. A data de cada cópia é o
vencimento da cobrança que a recebeu.
repeat_count: QUANTAS VEZES o item se repete. Omita para repetir sempre —
é o caso da mensalidade. Um número serve para compra parcelada:
{ "description": "Notebook", "amount": 50000,
"category_id": 5, "repeat_count": 6 }
O item entra em seis cobranças e some na sétima. Mínimo 2, máximo 999;
1 é recusado (uma cobrança só não é recorrente — use POST /items).
A contagem é por CÓPIAS FEITAS, não por linhas existentes: apagar o item
de uma fatura não devolve uma parcela ao cliente, e a sétima não nasce
para repor a apagada.
A DIFERENÇA PARA /items: um lançamento em /items entra numa cobrança só.
Um MODELO é aplicado a CADA cobrança que a série gerar. É o que dispensa
um agendador do seu lado para relançar a mensalidade todo mês.
charges_updated: quantas cobranças JÁ GERADAS receberam o item agora. O
cron materializa ~190 dias à frente, então criar o modelo depois da régua
encontra umas seis cobranças já nascidas sem ele — elas são alcançadas.
Pagas e vencidas ficam de fora: o cliente já recebeu aquelas cobranças.
effective_from (opcional, YYYY-MM-DD) muda o corte: só cobranças com
vencimento a partir dessa data.
IDEMPOTENTE por descrição, valor e sinal. O mesmo modelo pedido duas vezes
não vira dois: a resposta é 200 com "created": false e charges_updated 0 —
sem segunda aplicação, senão a mensalidade sairia dobrada.
Para não pegar as já geradas, mande effective_from com uma data futura.
/recurrences/{id}/item-templates/{tplId}
consumption_rec ou _pay (gerenciar)
Troca de plano numa chamada só.
Requisição
curl -X PATCH https://pagsim.com/api/v1/recurrences/78/item-templates/4 \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{ "amount": 19900 }'
Resposta
{ "id": 4, "description": "Mensalidade Pro", "amount": 19900,
"charges_updated": 6 }
Parcial: só os campos enviados mudam.
Existe para que trocar de plano não seja apagar-e-criar. Em duas chamadas,
uma falha na segunda deixaria o cliente com assinatura ativa e nenhum item
de plano dentro. Aqui, o modelo e as cópias ainda não cobradas mudam
juntos.
Aceita effective_from, igual ao POST.
/recurrences/{id}/item-templates/{tplId}
consumption_rec ou _pay (gerenciar)
Para de repetir e tira das cobranças abertas.
Requisição
curl -X DELETE https://pagsim.com/api/v1/recurrences/78/item-templates/4 \
-H "Authorization: Bearer psk_..."
Resposta
{ "id": 4, "deleted": true, "charges_updated": 6, "count": 0 }
POR PADRÃO TIRA A LINHA das cobranças ainda não vencidas. É o que o
cancelamento de plano precisa: sem isso a fatura do mês seguinte sairia
cobrando um plano que acabou — e são várias, porque o cron materializa
~190 dias.
VENCIDAS E PAGAS nunca são tocadas: o cliente já recebeu aquelas
cobranças.
Para só parar de copiar daqui para frente, mantendo o que já foi aplicado:
DELETE /recurrences/78/item-templates/4?keep_open_charges=true
Mesmo nome do parâmetro de /subscriptions/{id}/cancel, porque é a mesma
escolha.
/recurrences/{id}/items/{itemId}
consumption_rec ou _pay (gerenciar)
Cancela um item da cobrança aberta.
Requisição
curl -X DELETE https://pagsim.com/api/v1/recurrences/78/items/9 -H "Authorization: Bearer psk_..."
Resposta
{ "id": 9, "cancelled": true, "transaction_id": 4110, "total": 22500 }
Item que não é da cobrança aberta: 404. Já cancelado: responde igual (200).
LANÇAR E MEXER EM ITENS (desta rota, de POST /items e de item-templates)
exige a permissão de itens do lado da régua — consumption_rec numa régua a
receber, consumption_pay numa a pagar —, a mesma que o painel pede para
lançar um item. Ver a régua basta para LER os itens.
/subscriptions
rec (ver)
Lista. Filtros: status, contact_id, external_ref.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/subscriptions?status=active,past_due
Resposta
{ "data": [ { "id": 77, "external_ref": "boffice-4711",
"status": "past_due", "active": true, "days_late": 3 } ], "count": 1 }
/subscriptions/ref:{sua_ref}
rec (ver)
Busca pela SUA referência, sem tabela de-para.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/subscriptions/ref:boffice-4711
Resposta
{ "id": 77, "external_ref": "boffice-4711", "status": "active",
"active": true, "days_late": 0 }
active é o booleano que decide liberar acesso.
status detalha o porquê: active, past_due, expired, cancelled.
/subscriptions/{id}/cancel
rec (gerenciar)
Cancela. Remove pendentes ainda não vencidas.
Requisição
curl -X POST https://pagsim.com/api/v1/subscriptions/77/cancel \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{ "keep_open_charges": false }'
Resposta
{ "id": 77, "status": "cancelled", "active": false,
"future_charges_removed": 5 }
Cobranças VENCIDAS não são removidas: são dívida. As pendentes ainda não
vencidas saem (a menos que venha "keep_open_charges": true), cada uma com o
seu aviso "receivable.deleted" no webhook.
/subscriptions/{id}/reactivate
rec (gerenciar)
Religa a régua.
Requisição
curl -X POST https://pagsim.com/api/v1/subscriptions/77/reactivate -H "Authorization: Bearer psk_..."
Resposta
{ "id": 77, "status": "active", "active": true }
/receivables/{id}/attachments
files_rec (ver)
Lista, com link assinado e validade.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/receivables/1234/attachments
Resposta
{
"data": [
{ "id": 77, "name": "nota.pdf", "size": 20481, "mime": "application/pdf",
"url": "https://s3.../nota.pdf?X-Amz-Signature=...",
"url_expires_at": "2026-08-16T15:05:00Z",
"created_at": "2026-07-02T09:14:00Z" }
]
}
Numa conta de uma série, a lista inclui os arquivos anexados "em toda a
série" — como a tela mostra em cada parcela.
/receivables/{id}/attachments
files_rec (gerenciar)
Envia um arquivo. multipart/form-data, campo "file".
Requisição
curl -X POST https://pagsim.com/api/v1/receivables/1234/attachments \
-H "Authorization: Bearer psk_..." \
-F "file=@nota-fiscal.pdf"
Resposta
201 Created
{ "id": 78 }
O limite de arquivos por conta é o do plano; passou, 422 com "reason": "many".
Plano sem anexos: 403 plano_nao_permite (veja "features" em /me).
Tamanho e tipo de arquivo seguem as mesmas regras da tela.
/receivables/{id}/attachments/{attId}
files_rec (gerenciar)
Apaga o anexo.
Requisição
curl -X DELETE https://pagsim.com/api/v1/receivables/1234/attachments/78 \
-H "Authorization: Bearer psk_..."
Resposta
{ "deleted": true }
O anexo precisa ser DESTA conta (ou da série dela). Um id de anexo de
outra conta ou de um contato responde 404 — a permissão de anexos é por
área, e a rota de uma conta não apaga arquivo de outra.
E só o arquivo que a pessoa da chave enviou — a regra da tela de Equipe
("só os próprios, exceto o dono do espaço"). O de outra pessoa responde
403 sem_permissao; a chave do titular ou de um administrador apaga
qualquer um.
/contacts/{id}/attachments
files_contacts (ver)
Os anexos do contato.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/contacts/88/attachments
Resposta
{ "data": [ { "id": 91, "name": "contrato.pdf", "size": 20481,
"mime": "application/pdf", "url": "https://...",
"url_expires_at": "2026-08-16T15:05:00Z",
"created_at": "2026-07-02T09:14:00Z" } ] }
/contacts/{id}/attachments/{attId}
files_contacts (gerenciar)
Apaga um anexo do contato.
Requisição
curl -X DELETE https://pagsim.com/api/v1/contacts/88/attachments/91 -H "Authorization: Bearer psk_..."
Resposta
{ "deleted": true }
Mesma regra das contas: só o arquivo que a pessoa da chave enviou (o
titular ou um administrador apaga qualquer um); o de outra pessoa responde
403 sem_permissao.
/receivables/{id}/comments
comment_rec (gerenciar)
Anota um comentário (em /payables, comment_pay). Não há GET — ver abaixo.
Requisição
curl -X POST https://pagsim.com/api/v1/receivables/1234/comments \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{ "text": "Baixa conferida pelo ERP" }'
Resposta
201 Created
{ "id": 501 }
/contacts
contacts (ver)
Lista, com busca e filtros.
Requisição
curl -H "Authorization: Bearer psk_..." "https://pagsim.com/api/v1/contacts?q=fulano"
Resposta
{
"data": [
{ "id": 88, "name": "Fulano de Tal", "email": "fulano@exemplo.com",
"phone": "11999998888", "phone_ddi": "+55", "country": "BR",
"doc": "12345678900", "doc_type": "cpf",
"kind": { "id": 1, "name": "Cliente" },
"incomplete": false,
"created_at": "2026-01-10T08:00:00Z",
"updated_at": "2026-06-02T14:20:00Z" }
],
"meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 }
}
q a busca da tela: nome (sem diferença de acento), e-mail,
documento (com ou sem pontuação) e o VALOR dos campos
personalizados — é por ele que se acha "o cliente 4711 do
sistema X", guardado num campo próprio.
kind_id contatos que têm este tipo (um contato pode ter vários)
incomplete true = só os de cadastro incompleto (falta campo obrigatório)
updated_since, page, per_page — como nas contas.
/contacts/{id}
contacts (ver)
Um contato completo: dados fiscais, endereço, tipos, campos e anexos.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/contacts/88
Resposta
{
"id": 88,
"name": "Fulano de Tal",
"email": "fulano@exemplo.com",
"phone": "11999998888",
"phone_ddi": "+55",
"country": "BR",
"doc": "12345678900",
"doc_type": "cpf",
"kind": { "id": 1, "name": "Cliente" },
"incomplete": false,
"notes": null,
"kinds": [ { "id": 1, "name": "Cliente" }, { "id": 2, "name": "Fornecedor" } ],
"legal_name": null,
"fiscal_kind": "individual",
"im": null,
"zip": "01001-000",
"street": "Praça da Sé",
"number": "100",
"complement": null,
"district": "Sé",
"city": "São Paulo",
"state": "SP",
"custom_fields": [
{ "id": 2, "label": "Vendedor", "type": "text", "value": "Marina" }
],
"attachments": []
}
"kind" é o tipo principal; "kinds" traz todos. Os anexos só vêm para quem
tem files_contacts (ver).
/contacts
contacts (gerenciar)
Cria um contato.
Requisição
curl -X POST https://pagsim.com/api/v1/contacts \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{
"name": "Fulano de Tal",
"email": "fulano@exemplo.com",
"country": "BR",
"doc": "12345678900",
"doc_type": "cpf",
"kind_ids": [1, 2]
}'
Resposta
201 Created
{
"id": 88,
"name": "Fulano de Tal",
"email": "fulano@exemplo.com",
"kind": { "id": 1, "name": "Cliente" },
"kinds": [ { "id": 1, "name": "Cliente" }, { "id": 2, "name": "Fornecedor" } ]
}
OS CAMPOS são os da ficha do painel, com os MESMOS nomes da leitura:
name (obrigatório), email, phone, phone_ddi, country (padrão BR), doc,
doc_type, notes, kind_ids (lista) ou kind_id (um só), e os da aba de
dados fiscais: fiscal_kind (individual | company), legal_name, im, zip,
street, number, complement, district, city, state.
O documento é conferido como na tela (CPF/CNPJ com dígito verificador).
Erros vêm POR CAMPO: 422 dados_invalidos com "fields": { "doc": "..." }.
LIMITE DO PLANO: passou do número de contatos que o plano permite, 403
limite_do_plano com "limit".
CAMPOS PERSONALIZADOS ainda não são gravados pela API (a leitura vem em
"custom_fields"). Se o espaço tiver campo obrigatório, o contato criado
pela API nasce com "incomplete": true — o mesmo que a tela faz com a
criação rápida — e aparece no filtro de pendentes para a equipe completar.
/contacts/{id}
contacts (gerenciar)
Altera só o que veio.
Requisição
curl -X PATCH https://pagsim.com/api/v1/contacts/88 \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{ "phone": "11988887777" }'
Resposta
{ "id": 88, "name": "Fulano de Tal", "phone": "11988887777" }
Aceita os mesmos campos do POST. OS TIPOS só mudam se vierem: sem
"kind_ids" nem "kind_id" no corpo, o contato continua com os tipos que
tem; "kind_ids" troca a lista; "kind_id" deixa só aquele.
/contacts/{id}
contacts (gerenciar)
Exclui. Os lançamentos ficam com o nome dele.
Requisição
curl -X DELETE https://pagsim.com/api/v1/contacts/88 \
-H "Authorization: Bearer psk_..."
Resposta
{ "deleted": true, "id": 88, "unlinked": 12 }
Como no painel: os lançamentos do contato NÃO impedem a exclusão. Eles
ficam com o NOME do contato (em "party") e perdem o vínculo ("contact"
passa a null) — "unlinked" diz quantos.
Com muitos lançamentos o desligamento anda em lotes e pode não terminar
numa chamada. Aí a resposta é:
409 Conflict
{ "error": { "code": "exclusao_parcial", "unlinked": 500, "remaining": 1830 } }
Chame de novo: continua de onde parou, até vir "deleted": true.
/contacts/{id}/attachments
files_contacts (gerenciar)
Envia arquivo. multipart/form-data.
Requisição
curl -X POST https://pagsim.com/api/v1/contacts/88/attachments \
-H "Authorization: Bearer psk_..." \
-F "file=@contrato.pdf"
Resposta
201 Created
{ "id": 91 }
Plano sem anexos de contato: 403 plano_nao_permite.
/contacts/{id}/comments
comment_contacts (gerenciar)
Anota um comentário.
Requisição
curl -X POST https://pagsim.com/api/v1/contacts/88/comments \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{ "text": "Cliente pediu boleto" }'
Resposta
201 Created
{ "id": 502 }
Basta VER o contato e ter comment_contacts (gerenciar) — como na ficha do
painel. Os anexos, do mesmo jeito, com files_contacts.
/nfse
nfse (ver)
As notas fiscais do espaço, das mais novas para as mais antigas.
Requisição
curl -H "Authorization: Bearer psk_..." \
"https://pagsim.com/api/v1/nfse?status=emitida&issued_from=2026-12-01&issued_to=2026-12-31"
Resposta
{
"data": [
{
"id": 55,
"status": "emitida",
"number": "1007",
"verification_code": null,
"access_key": "35057082211222333000181000000000100726120000000041",
"dps_number": 41,
"dps_series": "1",
"module": "br-nacional",
"environment": "producao",
"origin": "manual",
"transaction_id": 1234,
"issued_at": "2026-12-10T14:03:00Z",
"cancelled_at": null,
"created_at": "2026-12-10T14:02:10Z",
"updated_at": "2026-12-10T14:05:41Z",
"error": null,
"files": {
"pdf": "https://pagsim.com/api/v1/nfse/55/pdf",
"xml": "https://pagsim.com/api/v1/nfse/55/xml"
}
}
],
"meta": { "total": 1, "page": 1, "per_page": 50, "total_pages": 1 }
}
Cada item é a nota inteira, igual a GET /nfse/{id}. A nota de ENSAIO (o
"testar com esta conta" da configuração) não é nota e nunca aparece.
FILTROS — valor inesperado é ignorado, como nas outras listas:
status uma ou mais situações, separadas por vírgula:
?status=fila,enviada são as que estão andando
issued_from AAAA-MM-DD — emitidas a partir deste dia
issued_to AAAA-MM-DD — emitidas até este dia
transaction_id só as notas de uma conta a receber
updated_since data ou instante ISO — só as que mudaram depois disso
page, per_page como nas contas (padrão 50, máximo 200)
O PERÍODO É O DA EMISSÃO: nota ainda não emitida (na fila, com erro,
descartada) não tem dia de emissão e fica fora de qualquer período. Os dias
são em UTC, como os instantes da API.
TODAS AS SITUAÇÕES saem, inclusive a descartada — ao contrário da lista do
painel, que a esconde. Quem sincroniza precisa ver a nota que pediu sair da
fila sem ter sido emitida (a descartada não tem aviso no webhook). Para não
vê-la, filtre por status.
/nfse/{id}
nfse (ver)
Uma nota: situação, número oficial, DPS, erro e os links dos arquivos.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/nfse/56
Resposta
{
"id": 56,
"status": "erro",
"number": null,
"verification_code": null,
"access_key": null,
"dps_number": null,
"dps_series": "1",
"module": "br-nacional",
"environment": "producao",
"origin": "manual",
"transaction_id": 1240,
"issued_at": null,
"cancelled_at": null,
"created_at": "2026-12-10T15:00:02Z",
"updated_at": "2026-12-10T15:01:10Z",
"error": {
"code": "dados",
"message": "Faltam dados para a nota, ou algum não confere: Falta: CPF/CNPJ do tomador; CEP do tomador: CEP inválido (8 dígitos)."
},
"files": { "pdf": null, "xml": null }
}
AS SITUAÇÕES ("status"), com os nomes do painel:
fila na fila: ainda não saiu daqui, ou vai sair de novo depois de
um problema passageiro (rede, governo fora do ar) — a fila
tenta sozinha
enviada enviada ao governo, esperando a resposta (consultada sozinha)
emitida tem número oficial: é documento fiscal
erro parou, e não sai sozinha desta situação — veja "error"
cancelando o cancelamento foi pedido (no painel) e espera o governo
cancelada cancelada no governo; os arquivos continuam disponíveis
descartada nunca foi ao governo: descartada no painel, ou a conta foi
cancelada ou apagada antes do envio
OS CAMPOS:
number o número OFICIAL da NFS-e, o que o governo deu. Texto,
porque zero à esquerda não pode sumir. null até emitir
verification_code o código de autenticidade (Barueri)
access_key a chave de acesso (nacional)
dps_number o NOSSO número, do RPS (Barueri) ou da DPS (nacional),
dps_series e a série. O número nasce no primeiro envio ao governo
— antes disso, null
module o sistema de nota: br-nacional, br-barueri
environment homologacao = nota de TESTE, sem valor fiscal;
producao = de verdade
origin manual (pedida no painel ou pela API) ou auto (a regra
automática do espaço)
transaction_id a conta a receber de origem. Pode ser de uma conta já
apagada: a nota é documento fiscal e fica
issued_at, cancelled_at, created_at, updated_at — instantes em UTC
files links da PRÓPRIA API para o PDF e o XML oficiais (exigem
a chave, como tudo aqui). null enquanto o arquivo não
está guardado: a fila busca no governo logo depois da
emissão. Em Barueri não há PDF — a nota é a página dela
no portal da prefeitura
"ERROR" vem sempre que a nota tem um código de erro, e não só na situação
erro: numa nota na fila, é o problema passageiro com que ela está tentando
de novo; numa emitida, o cancelamento recusado ou não confirmado (a nota
continua emitida); numa descartada, o porquê. Fora disso, null. "code" é
estável — programe contra ele. "message" é o texto do painel, em português:
a lista do que falta, ou o texto oficial do governo, como veio (é o que o
suporte da prefeitura vai pedir).
O ERRO DE DADO (code "dados") se resolve na CONTA ou no CONTATO: corrija o
que a mensagem diz — PATCH /contacts/{id} ou PATCH /receivables/{id} — e
peça a nota de novo, com POST /receivables/{id}/nfse. Vem uma nota nova; a
que deu erro continua na lista, como histórico.
Nota de ensaio, nota de outro espaço e id que não existe respondem o mesmo
404 nao_encontrado.
/nfse/{id}/pdf
nfse (ver)
O PDF oficial (DANFSe), como arquivo.
Requisição
curl -H "Authorization: Bearer psk_..." \
-o nfse-1007.pdf https://pagsim.com/api/v1/nfse/55/pdf
Resposta
200 OK
Content-Type: application/pdf
Content-Disposition: attachment; filename="nfse-1007.pdf"
(o arquivo)
O arquivo sai da própria API, autenticado pela chave — não é um link
temporário que expira. Sem PDF guardado: 404 arquivo_indisponivel, em JSON.
Olhe "files" em GET /nfse/{id} antes de baixar: o link só vem quando há
arquivo.
/nfse/{id}/xml
nfse (ver)
O XML oficial, como arquivo.
Requisição
curl -H "Authorization: Bearer psk_..." \
-o nfse-1007.xml https://pagsim.com/api/v1/nfse/55/xml
Resposta
200 OK
Content-Type: application/xml
Content-Disposition: attachment; filename="nfse-1007.xml"
(o arquivo)
O XML que o governo devolveu: o documento fiscal de verdade, o que a
contabilidade pede. Sem XML guardado: 404 arquivo_indisponivel.
/receivables/{id}/nfse
nfse (gerenciar) + rec (ver)
Pede a nota fiscal de uma conta a receber. SEM CORPO: a nota sai da configuração do espaço.
Requisição
curl -X POST https://pagsim.com/api/v1/receivables/1234/nfse \
-H "Authorization: Bearer psk_..."
Resposta
202 Accepted
{
"id": 57,
"status": "fila",
"number": null,
"dps_number": null,
"module": "br-nacional",
"environment": "producao",
"origin": "manual",
"transaction_id": 1234,
"issued_at": null,
"error": null,
"files": { "pdf": null, "xml": null },
...
}
A NOTA É SEMPRE DE UMA CONTA, E O PEDIDO NÃO LEVA DADO NENHUM. Ela é montada
pela configuração de nota fiscal do espaço — de onde vem cada campo (o CPF
ou CNPJ do cliente, o endereço, o serviço, o valor), ligado pelo titular em
Ajustes → Nota fiscal — a partir da conta e do contato dela: o mesmo
caminho do botão "Emitir nota" da conta no painel.
POR QUÊ: aceitar valores no pedido pularia essa configuração, e a nota
diria uma coisa enquanto a conta e o contato dizem outra — é a nota que vai
para o governo, e a conta é o que o resto do sistema (os relatórios, a
fatura, o pacote da contabilidade) enxerga.
PARA MUDAR ALGUM VALOR da nota, altere ANTES a conta (PATCH
/receivables/{id}) ou o contato (PATCH /contacts/{id}) e então peça a nota.
Qualquer corpo que não seja vazio ou {} é RECUSADO — e não ignorado, para
ninguém achar que o valor enviado foi para a nota:
422
{ "error": { "code": "corpo_nao_aceito",
"message": "Esta rota não recebe dados da nota fiscal: ...",
"transaction_id": 1234, "contact_id": 88 } }
ASSÍNCRONA: a nota entra na FILA (202, "status": "fila") e sai em segundo
plano — o governo pode levar de segundos a minutos. O resultado chega pelo
webhook (nfse.issued ou nfse.failed, com a nota no corpo) ou em
GET /nfse/{id}.
IDEMPOTENTE: a conta que já tem nota VIVA responde 409 com ELA — repetir o
pedido depois de uma queda de rede não cria a segunda:
409
{ "error": { "code": "nfse_ja_existe",
"message": "Esta conta já tem uma nota fiscal emitida (#55, nº 1007).",
"nfse": { "id": 55, "status": "emitida", "number": "1007", ... } } }
Viva é a nota na fila, enviada, emitida ou em cancelamento — e também a
parada com erro DEPOIS de um envio sem resposta: ela pode existir no
governo, e a conta não ganha outra enquanto isso (resolva no painel, em
"Tentar de novo"). Cancelada, descartada ou com erro antes de sair daqui
não ocupam a conta: o pedido cria uma nota nova.
AS MESMAS TRAVAS DO PAINEL — a primeira que falhar responde:
403 sem_permissao falta rec (ver)
404 nao_encontrado a conta não existe, ou não é deste espaço
403 sem_permissao falta nfse (gerenciar)
403 plano_nao_permite o plano não inclui nota fiscal
403 somente_leitura o espaço está em modo somente leitura
422 corpo_nao_aceito veio corpo (veja acima)
409 nfse_ja_existe a conta já tem nota viva
422 conta_cancelada a conta está cancelada
422 nfse_impedida o espaço não pode emitir agora. "reason" é o
primeiro motivo; "reasons", todos:
modulo nenhum sistema de nota escolhido
certificado falta o certificado digital A1
certificado_vencido o certificado venceu
moeda o espaço não é em reais
campos dado obrigatório sem origem
Quem resolve é o titular, no painel (Ajustes →
Nota fiscal).
Em /payables/{id}/nfse: 422 so_receivables.
Um dado da CONTA ou do CONTATO que falta ou não confere (o CPF, o CEP) não
é conferido aqui: a nota entra na fila e para com o erro "dados", que chega
como nfse.failed — com a lista do que corrigir.
CANCELAR uma nota, a configuração e o certificado ficam só no painel.
/categories
rec ou pay (ver)
Categorias ativas — só as do lado que a chave vê (e as de "ambas").
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/categories
Resposta
{
"data": [
{ "id": 5, "name": "Serviços", "direction": "in", "color": "#4f0ee6" },
{ "id": 6, "name": "Aluguel", "direction": "out", "color": "#8087aa" }
]
}
/accounts
rec ou pay (ver)
Contas bancárias e carteiras.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/accounts
Resposta
{
"data": [
{ "id": 2, "name": "Banco Inter", "kind": "bank" },
{ "id": 3, "name": "Caixinha", "kind": "cash" }
]
}
/contact-kinds
contacts (ver)
Tipos de contato.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/contact-kinds
Resposta
{ "data": [ { "id": 1, "name": "Cliente" }, { "id": 2, "name": "Fornecedor" } ] }
/indices
rec (ver)
Índices de correção monetária.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/indices
Resposta
{ "data": [ { "id": 1, "name": "IGPM", "notes": "Reajuste anual dos aluguéis" } ] }
O índice é só um RÓTULO: o percentual não fica guardado nele. Quem aplica
a correção digita a taxa do período na hora. Use o id em recurrences.index_id
para marcar qual índice rege a série.
Só os índices ATIVOS aparecem aqui. Um índice arquivado não aceita vínculo
novo (422 em "index_id"); ao arquivar pelo painel, o dono escolhe para onde
vão as contas em aberto e as séries que o usavam.
/rulesets
rec (ver)
Conjuntos de juros, multa e desconto, com as regras.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/rulesets
Resposta
{
"data": [
{ "id": 50, "name": "Padrão", "active": true, "is_default": true,
"rules": [
{ "id": 1, "name": "Multa", "effect": "fee", "when": "after",
"days": 1, "mode": "percent", "value": 200, "period": "once",
"compound": false, "pro_rata": false, "cap": 0, "priority": 1 },
{ "id": 2, "name": "Juros", "effect": "fee", "when": "after",
"days": 1, "mode": "percent", "value": 100, "period": "month",
"compound": false, "pro_rata": true, "cap": 0, "priority": 2 }
] },
{ "id": 51, "name": "Sem juros", "active": true, "is_default": false,
"rules": [] }
],
"count": 2
}
ATENÇÃO À ESCALA de "value":
mode "fixed" → centavos. 500 = R$ 5,00
mode "percent" → CENTÉSIMOS de ponto percentual.
200 = 2% · 100 = 1% · 3 = 0,03%
Divida por 100 para ter o percentual. Teto: 10000 (100%).
É a mesma escala que o painel guarda — nasceu para não perder casa decimal
em juros diários como 0,033%.
"effect": fee = acréscimo, discount = abatimento.
"when": before | on_due | after | always, com "days" contados do vencimento.
"period": once (uma vez) | day | month (repete no período).
"cap": teto em centavos; 0 = sem teto.
"is_default": o conjunto que entra sozinho quando ninguém escolhe — mande este
id se quiser o mesmo comportamento do painel.
/custom-fields?area=transactions|contacts
contas ou contacts (ver)
A definição dos campos personalizados.
Requisição
curl -H "Authorization: Bearer psk_..." \
"https://pagsim.com/api/v1/custom-fields?area=transactions"
Resposta
{
"data": [
{ "id": 3, "key_name": "contrato", "label": "Contrato", "type": "text",
"options": null, "required": false, "area": "rec", "sort": 1 },
{ "id": 4, "key_name": "centro_custo", "label": "Centro de custo",
"type": "select", "options": ["Comercial","Operações"],
"required": true, "area": "both", "sort": 2 }
]
}
area=transactions (padrão) exige ver contas a pagar ou a receber, e traz os
campos do lado que a chave vê ("area": in, out ou both). area=contacts
exige ver contatos, e cada campo traz também "unique" (o painel recusa
valor repetido dentro do espaço).
"options" é a lista de valores aceitos num campo "select"; null nos outros
tipos.
curl -X POST https://pagsim.com/api/v1/receivables \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{
"description": "Mensalidade de julho",
"amount": 15000,
"due_date": "2026-07-10",
"contact_id": 88,
"category_id": 5
}'
{
"id": 1234,
"direction": "in",
"description": "Mensalidade de julho",
"amount": 15000,
"paid_amount": null,
"currency": "BRL",
"due_date": "2026-07-10",
"status": "pending",
"category": { "id": 5, "name": "Serviços" },
"contact": { "id": 88, "name": "Fulano" },
"custom_fields": [ { "id": 3, "label": "Contrato", "type": "text", "value": "CT-2026-01" } ],
"items": null,
"corrections": [],
"attachments": []
}
curl -X POST https://pagsim.com/api/v1/receivables/1234/settle \
-H "Authorization: Bearer psk_..." \
-H "Content-Type: application/json" \
-d '{ "settled_at": "2026-07-09", "paid_amount": 15000 }'
Cada anexo vem com um link assinado e temporário, e com
url_expires_at dizendo até quando ele vale — o arquivo mora em S3. Não
guarde a URL numa tabela sua: busque de novo quando for baixar. Sem esse campo, a
expiração só apareceria meses depois, quando o download quebrasse sem explicação.
curl -X POST https://pagsim.com/api/v1/receivables/1234/attachments \
-H "Authorization: Bearer psk_..." \
-F "file=@nota-fiscal.pdf"
| Parâmetro | Valores |
|---|---|
status | pending, overdue, paid, received, cancelled |
due_from | AAAA-MM-DD — vencimento a partir de |
due_to | AAAA-MM-DD — vencimento até |
contact_id | só de um contato |
category_id | só de uma categoria |
account_id | só de uma conta |
recurrence_id | só as cobranças geradas por uma recorrência |
q | a busca da tela: descrição e nome da outra parte, sem diferença de acento, e o número da fatura |
updated_since | data ou instante ISO — só o que mudou depois disso |
page | a partir de 1 |
per_page | padrão 50, máximo 200 |
Estes valem para /receivables e /payables. Os de
/contacts (q, kind_id, incomplete,
updated_since), de /recurrences e de /nfse
(status, issued_from, issued_to,
transaction_id, updated_since) estão nas próprias rotas.
Parâmetro desconhecido é ignorado, não recusado — assim uma versão futura da API não quebra o que você já escreveu.
Toda listagem responde no mesmo formato, inclusive quando vazia:
{
"data": [ ... ],
"meta": { "total": 137, "page": 1, "per_page": 50, "total_pages": 3 }
}
Para sincronizar sem puxar tudo, guarde o instante da última leitura e use
updated_since. É a diferença entre trazer o que mudou e trazer a base
inteira todo dia.
Sempre no mesmo formato. Programe contra o code, nunca contra a
mensagem — o texto pode ser reescrito a qualquer momento; o código, não.
{ "error": { "code": "sem_permissao", "message": "..." } }
| HTTP | code | Quando |
|---|---|---|
| 400 | json_invalido | O corpo não é um objeto JSON válido. |
| 400 | sem_arquivo | Envio de anexo sem o campo "file" (multipart/form-data). |
| 401 | sem_credencial | Falta o cabeçalho Authorization. |
| 401 | credencial_invalida | Chave inválida, revogada, ou de uma conta suspensa. |
| 403 | sem_acesso | A pessoa da chave não faz mais parte do espaço (removida, ou convite não aceito). |
| 403 | espaco_arquivado | O espaço foi arquivado ou excluído. |
| 403 | espaco_bloqueado | Assinatura vencida ou espaço bloqueado. |
| 403 | plano_sem_api | O plano do espaço não inclui acesso à API. |
| 403 | sem_permissao | A pessoa da chave não tem essa permissão no painel (inclui apagar anexo enviado por outra pessoa). |
| 403 | somente_leitura | O espaço está em modo somente leitura. |
| 403 | plano_nao_permite | O plano não inclui o recurso (ex.: link de pagamento, anexos, nota fiscal). |
| 403 | limite_do_plano | O limite do plano foi atingido (ex.: número de contatos). Traz "limit". |
| 404 | nao_encontrado | Não existe — ou não é deste espaço, ou é de um lado que a chave não vê. |
| 404 | not_found | O mesmo, nas rotas /recurrences e /subscriptions. |
| 404 | rota_nao_encontrada | Rota desconhecida. |
| 404 | arquivo_indisponivel | O PDF ou o XML da nota ainda não está guardado (ou não pôde ser lido agora). Veja "files". |
| 405 | metodo_nao_permitido | Método não suportado nesta rota (as de /nfse são só GET). |
| 405 | method_not_allowed | O mesmo, nas rotas /recurrences e /subscriptions. |
| 409 | exige_decisao_estorno | Conta paga online: informe "refund" (cancelar/reabrir). |
| 409 | external_ref_em_uso | Já existe recorrência com esta external_ref. Traz o "recurrence_id". |
| 409 | exclusao_parcial | Contato com muitos lançamentos: chame de novo para continuar. |
| 409 | nfse_ja_existe | A conta já tem nota fiscal viva. Traz a nota em "nfse". |
| 422 | dados_invalidos | Algum campo não passou na validação. Veja "field"/"fields" (e "reason", em /permissions/check). |
| 422 | campo_invalido | O mesmo, nas rotas /recurrences. Veja "field". |
| 422 | data_invalida | Data fora do formato YYYY-MM-DD, ou que não existe. Veja "field". |
| 422 | conta_de_itens | Valor ou categoria de uma conta de itens (é a soma dos itens). |
| 422 | nao_foi_possivel | A operação não coube no estado da conta. Veja "reason". |
| 422 | item_invalido | Item de recorrência inválido. Veja "field". |
| 422 | serie_sem_itens | A recorrência é de valor fixo e não aceita itens. |
| 422 | serie_encerrada | Recorrência encerrada: não há próxima cobrança. |
| 422 | sem_conta_aberta | Não há cobrança aberta agora — tente mais tarde. |
| 422 | so_receivables | Link de pagamento e nota fiscal só existem em conta a receber. |
| 422 | conta_cancelada | Não se gera link nem nota fiscal de uma conta cancelada. |
| 422 | corpo_nao_aceito | POST /receivables/{id}/nfse com corpo: a nota não recebe dados — mude a conta ou o contato. |
| 422 | nfse_impedida | O espaço não pode emitir nota agora (módulo, certificado, campos). Veja "reason" e "reasons". |
| 422 | provedor_sem_estorno | O provedor do pagamento não aceita estorno pela API. |
| 422 | estorno_falhou | O estorno foi recusado; nada foi alterado. Veja "motivo". |
| 429 | muitas_requisicoes | Limite excedido. |
| 500 | erro_interno | Erro nosso. Traz "reference" para citar no suporte. |
Um id de outro espaço responde 404, não 403. Um 403 confirmaria que aquele id existe em algum lugar — e isso já é informação.
600 requisições por minuto por IP e 300 por minuto por chave. Ao estourar, a resposta é
429 e a espera é de um minuto. O bloqueio é curto de propósito: quase sempre a
causa é um laço mal escrito, e travar por quinze minutos transformaria um erro de
programação numa manhã perdida.
Configurados na mesma tela da chave de API. Um endereço por pessoa, por espaço.
Cada um recebe só o que pode ver. O aviso segue as permissões de quem cadastrou
o endereço — as mesmas da chave dela: quem não vê contas a pagar não recebe
payable.*, quem não vê contatos não recebe contact.*, quem não vê
notas fiscais não recebe nfse.*. E os avisos param no mesmo instante em que a
chave pararia (a pessoa saiu da equipe, a conta foi suspensa, o espaço foi arquivado, o plano
deixou de incluir API — ou, para nfse.*, deixou de incluir nota fiscal).
{
"event": "receivable.updated",
"space_id": 12,
"entity": "receivable",
"id": 1234,
"at": "2026-08-16T12:00:00Z"
}
O aviso diz o que mudou, não qual foi a mudança. Ao receber, consulte
GET /receivables/1234 e leia o estado atual.
Isso não é economia: resolve o problema mais chato de webhook. Duas mudanças rápidas podem chegar fora de ordem, e com uma carga descritiva você gravaria o estado antigo por cima do novo. Lendo o estado atual, a ordem deixa de importar.
Pelo mesmo motivo, avisos repetidos da mesma conta são agrupados: cinco edições em dez segundos viram um POST, não cinco.
A nota fiscal é a exceção: o aviso dela traz a nota inteira — veja Nota fiscal, abaixo.
receivable.created · receivable.updated ·
receivable.deleted · o mesmo para payable,
contact e recurrence · e, da nota fiscal,
nfse.queued · nfse.issued · nfse.failed ·
nfse.cancelled.
Qualquer alteração dispara updated: status, valor, dados, item de consumo,
arquivo anexado ou apagado, comentário. E dispara também quando a mudança vem do
painel, de um pagamento online ou da geração automática das cobranças de uma
recorrência (receivable.created a cada cobrança nova) — não só pela API.
O que não dispara aviso: a passagem automática para "vencida" (compare o
due_date com o dia de hoje do espaço), a correção monetária aplicada em lote
e as alterações "em toda a série" feitas pelo painel (dados ou itens repetidos), que mexem
em muitas contas de uma vez — ali só a parcela editada avisa. Para esses casos, sincronize
com updated_since: o updated_at das contas muda normalmente.
Ao excluir um contato, os lançamentos dele perdem o vínculo (e ficam com o nome em
party); chega só o contact.deleted.
Antes destes eventos, a assinatura só era vista por reflexo: quando uma
cobrança dela mudava, chegava um receivable.updated e você consultava
/subscriptions para reler o estado. O que não passava por uma
cobrança — desligar a régua pelo painel, trocar o valor do plano — era silêncio.
Agora recurrence.updated chega quando a régua muda de valor, de
frequência, de contato, e quando é ligada ou desligada, seja pelo painel, pela
API ou por /subscriptions/{id}/cancel.
{
"event": "recurrence.updated",
"space_id": 12,
"entity": "recurrence",
"id": 77,
"at": "2026-08-19T12:00:00Z"
}
Ao receber, consulte GET /recurrences/77 para o que foi configurado, ou
GET /subscriptions/77 para o estado (em dia, atrasada, cancelada).
Um detalhe do agrupamento: como avisos pendentes da mesma entidade viram um só,
uma régua criada e apagada antes da entrega chega como created, e o
GET devolve 404. Trate o 404 como "essa régua não existe mais" — o
evento diz que algo mudou no id, não o que mudou.
Um aviso a cada passo que importa para quem integra — a nota venha da API, do botão do painel ou da regra automática do espaço:
| Evento | "status" | Quando |
|---|---|---|
nfse.queued | fila | a nota entrou na fila de emissão |
nfse.issued | emitida | o governo emitiu: já tem número oficial |
nfse.failed | erro | parou com erro — o motivo está em data.error |
nfse.cancelled | cancelada | a nota foi cancelada no governo |
Aqui a carga traz a nota, em data — exatamente o que
GET /nfse/{id} responderia, com o número, o erro e os links do PDF e do XML.
Quem recebe nfse.issued já tem o que precisa, sem uma segunda chamada:
{
"event": "nfse.issued",
"space_id": 12,
"entity": "nfse",
"id": 55,
"at": "2026-12-10T14:05:41Z",
"data": {
"id": 55,
"status": "emitida",
"number": "1007",
"verification_code": null,
"access_key": "35057082211222333000181000000000100726120000000041",
"dps_number": 41,
"dps_series": "1",
"module": "br-nacional",
"environment": "producao",
"origin": "manual",
"transaction_id": 1234,
"issued_at": "2026-12-10T14:03:00Z",
"cancelled_at": null,
"created_at": "2026-12-10T14:02:10Z",
"updated_at": "2026-12-10T14:05:41Z",
"error": null,
"files": {
"pdf": "https://pagsim.com/api/v1/nfse/55/pdf",
"xml": "https://pagsim.com/api/v1/nfse/55/xml"
}
}
}
{
"event": "nfse.failed",
"space_id": 12,
"entity": "nfse",
"id": 56,
"at": "2026-12-10T15:01:12Z",
"data": {
"id": 56,
"status": "erro",
"transaction_id": 1240,
"error": {
"code": "dados",
"message": "Faltam dados para a nota, ou algum não confere: Falta: CPF/CNPJ do tomador."
},
...
}
}
A nota é lida na hora do envio, não na hora do evento. Continua valendo o que vale
para os outros avisos: você recebe o estado atual, e a ordem de chegada deixa de
importar. E o agrupamento aqui fica com o evento mais recente: se a nota entrou na
fila e foi emitida antes de o primeiro aviso sair, chega um POST,
nfse.issued, com a nota emitida — não um queued atrasado. Por
isso, decida pelo data.status; o evento diz o último passo que aconteceu.
Não geram aviso: enviada e cancelando (passos do meio, que
a fila resolve sozinha), a descartada (nunca foi ao governo — veja-a em
GET /nfse, que lista todas as situações) e a nota de ensaio da configuração, que
não é nota.
Recebeu nfse.failed com "code": "dados"? Corrija a conta ou o
contato que a mensagem aponta e peça a nota de novo com
POST /receivables/{id}/nfse.
Cada entrega traz:
X-Pagsim-Signature: t=1755350400,v1=5f3a...
O v1 é HMAC-SHA256 de "{t}.{corpo cru}" com o
segredo do seu webhook. Use o corpo cru, antes de qualquer parse: reserializar
o JSON muda um espaço e a assinatura não bate.
<?php
$corpo = file_get_contents('php://input');
$h = $_SERVER['HTTP_X_PAGSIM_SIGNATURE'] ?? '';
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $h, $m);
$esperado = hash_hmac('sha256', $m[1] . '.' . $corpo, SEU_SEGREDO);
// hash_equals e não ==: a comparação de tempo constante evita que o
// atacante descubra a assinatura byte a byte medindo o tempo de resposta.
if (!hash_equals($esperado, $m[2] ?? '')) { http_response_code(401); exit; }
// Recusa o que for velho: sem isto, quem capturasse uma entrega poderia
// reenviá-la mil vezes depois e a assinatura continuaria válida.
if (abs(time() - (int)$m[1]) > 300) { http_response_code(401); exit; }
http_response_code(200); // responda AGORA, processe depois
$d = json_decode($corpo, true);
# Node
const crypto = require('crypto');
const [, t, v1] = req.headers['x-pagsim-signature'].match(/t=(\d+),v1=([a-f0-9]+)/);
const esperado = crypto.createHmac('sha256', SEGREDO)
.update(t + '.' + req.rawBody).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(esperado), Buffer.from(v1))) return res.sendStatus(401);
# Python
import hmac, hashlib, re, time
t, v1 = re.match(r"t=(\d+),v1=([a-f0-9]+)", request.headers["X-Pagsim-Signature"]).groups()
esperado = hmac.new(SEGREDO.encode(), f"{t}.".encode() + request.get_data(), hashlib.sha256).hexdigest()
if not hmac.compare_digest(esperado, v1): abort(401)
Responda qualquer 2xx assim que receber, e processe depois — o tempo limite é de 5 segundos. Falhando, tentamos de novo depois de 5, 15, 60 e 240 minutos — cinco tentativas ao todo; depois da quinta, a entrega é marcada como falha. Após 20 falhas seguidas o webhook é desligado sozinho, e o aviso aparece na tela da chave de API, com as últimas entregas; salvar o endereço de novo religa.
A URL precisa ser pública em http ou https. Endereços internos
e privados são recusados no cadastro — inclusive nomes que resolvem para eles.
Dúvida que a página não responde? Fale com quem administra o seu espaço na Pagsim.