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, em Ajustes → Chave de API (o ícone de engrenagem). O titular e quem é da equipe usam o mesmo caminho; para a equipe, os Ajustes mostram só a própria chave. 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.
Sobre a assinatura vencida: a data que vale é o vencimento do plano na tela Assinatura do
painel (a assinatura do espaço com a Pagsim, que fica só no painel). Ela muda quando o plano é
renovado, trocado ou cancelado, ou num acordo com a Pagsim, e a carência vale antes de a
chave parar. Para a integração, o sinal é 403 espaco_bloqueado.
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.
As configurações do espaço também ficam só no painel — e valem para as contas criadas pela API do mesmo jeito
que para as do painel: a emissão automática da nota fiscal e o e-mail da nota ao cliente
("todas" ou só as contas que atendem às condições), a correção monetária por índice, as
observações da fatura e os meios de pagamento de cada conta. As condições olham a categoria
da conta (em algumas, também a de um item dela), o tipo do contato e, onde a tela oferece, os
campos personalizados da conta ou do contato — os mesmos de GET /custom-fields.
Assim, a fatura de uma conta criada pela API (o link de POST …/payment-link)
mostra só os meios de pagamento e as observações cujas condições ela atende.
POST /receivables/{id}/nfse é o botão "Emitir nota" do painel: pede a nota da
conta sem olhar as condições da emissão automática. A assinatura do espaço com a Pagsim
(plano, períodos, cancelamento) também fica no painel.
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 },
"over_limit": [],
"over_limit_blocking": false
}
OVER_LIMIT: os limites do plano que o espaço PASSOU (vazio quando cabe) —
os mesmos números do 403 limite_excedido (veja Limites). Com algum item e
over_limit_blocking true, criar e editar estão suspensos até apagar ou
assinar um plano maior; apagar continua liberado.
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).
PAID_AMOUNT é o que entrou. Na conta quitada, o valor da baixa (ou o que o
provedor pagou). Na conta EM ABERTO, quando não é null, é o que já entrou
pelo pagamento online e ficou com o espaço: um pagamento parcial, ou o que
sobrou de uma devolução ou contestação parcial, que reabrem a conta. O que
ainda falta pagar é o que a fatura mostra, com os juros, a multa e o
desconto do dia.
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; false (ou null, ""
ou ausente) deixa em aberto. Valem os sim/não desta API:
true/false, 1/0, "1"/"0", "true"/"false", "yes"/"no" e
"on"/"off" (no texto, maiúsculas e espaços nas pontas não
importam). Outro valor ("sim", "S", 2) é 422
dados_invalidos com "field": "settled", e nada é criado.
Sem settled_at, a data do pagamento é o vencimento quando
ele já passou, e hoje quando não (nunca um dia que ainda
não chegou)
settled_at YYYY-MM-DD: a data em que ela FOI paga/recebida. SÓ VALE COM
"settled": true — sem ele (ou com "settled": false) é
ignorado: copiar o objeto do GET de uma conta paga cria a
cópia EM ABERTO. A mesma regra do /settle: pode ser antes
do vencimento e antes de hoje; depois de hoje (no fuso do
espaço) é 422 data_futura, antes de 2000-01-01 é 422
data_antiga, data que não existe (ou valor que não é
texto) é 422 data_invalida — todos com "field": "settled_at"
has_consumption true (os mesmos sim/não do settled) = 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).
false, "false" ou ausente = conta comum, com o "amount".
Outro valor ("sim", 2) é 422 dados_invalidos com "field":
"has_consumption", e nada é criado
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 o mês do vencimento acabou).
COTA DO MÊS: o 422 com "field": "quota" traz também "limit" (lançamentos
por mês que o plano permite) e "used" (quantos o mês do vencimento já tem).
Apague um lançamento que vence nesse mês ou assine um plano maior.
{ "error": { "code": "dados_invalidos", "field": "quota",
"limit": 10, "used": 10,
"message": "O plano deste espaço permite até 10 lançamentos por mês, e o mês deste vencimento (07/2026) já tem 10. Apague um lançamento desse mês ou assine um plano maior." } }
/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.
settled_at — A DATA DO PAGAMENTO de uma conta já baixada À MÃO (é o lápis
do "Pago em" do painel). Muda só a data: o valor recebido e os juros
congelados na baixa ficam como estão. Vale também para a baixa à mão que
um pagamento online substituiu depois (a data continua a que você
informou) e para o pagamento online PARCIAL completado com uma baixa à mão.
PATCH /payables/1234 { "settled_at": "2026-11-05" }
{ "id": 1234, "status": "paid", "settled_at": "2026-11-05", ... }
O MESMO settled_at de volta não é pedido de mudança: igual ao atual, ou
null ou "" (o que o GET traz numa conta em aberto) — o objeto do GET
devolvido inteiro, com outro campo alterado — é ignorado: não muda nada e
não dá erro, como amount/category_id da conta de itens. Só uma data
DIFERENTE da atual passa pela regra abaixo.
A mesma regra de data do /settle (422 data_futura, data_antiga ou
data_invalida, com "field": "settled_at"). Quando não cabe, 409 — e nada
do PATCH é gravado, nem os outros campos:
409 pago_online a conta foi paga pelo PROVEDOR (link da fatura,
banco): a data vem dele e não se altera. Traz
"module" (ex.: "stripe"). Exceção: a baixa
automática que a versão anterior gravou no dia UTC
(quando o dia UTC do pagamento era outro que o dia
no fuso do espaço; em São Paulo, o pago entre 21h e
meia-noite) aceita EXATAMENTE o dia local do
provedor — a recusa de outra data traz esse dia
em "provider_date"
409 conta_em_aberto a conta não está paga: para dar baixa numa data,
use POST .../settle com "settled_at"
409 conta_cancelada a conta está cancelada
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 }
CONTA COM PAGAMENTO EM PROCESSAMENTO não se exclui: 409
pagamento_em_processamento, e nada muda. É a cobrança automática no cartão
do cliente que ainda espera a confirmação, ou um boleto gerado no provedor
e ainda não pago (que o cliente pode pagar a qualquer momento) — o
dinheiro que chegasse depois ficaria sem conta — e, numa conta a pagar, o
pagamento pelo banco ainda em andamento. O boleto que não é pago libera a
conta em até 7 dias. Na conta a receber, cancele a conta (POST .../cancel)
ou espere a confirmação. Na conta a pagar, cancele o pagamento no painel
(Acompanhar o pagamento pelo banco › Cancelar) ou espere o banco
concluí-lo: cancelar a conta não cancela o pagamento no banco.
CONTA CANCELADA COM PAGAMENTO A DEVOLVER (um pagamento do provedor que
não foi devolvido: o que entrou depois de cancelada, ou o da conta paga e
cancelada com "refund": false) também não se exclui: 409
pagamento_a_devolver, e nada muda. Devolva antes (POST .../cancel com
"refund": true); se a devolução já foi pedida, espere a confirmação do
provedor; se o pagamento não se devolve pela API, devolva pelo painel do
provedor (a conta se exclui quando o aviso do provedor registra a
devolução no Pagsim). A mensagem do erro diz qual é o caso. Um pedido de
devolução PARCIAL que ficou sem resposta do provedor (tempo esgotado ou
erro dele no "refund_amount") prende o pagamento: sem outro pagamento a
devolver na conta, o "refund": true sem valor dá 422 estorno_falhou com
"motivo": "estorno_em_andamento" (o valor do pedido vem no
"pending_refund_amount" do 409 exige_decisao_estorno e na mensagem do 409
pagamento_a_devolver deste DELETE; a "mensagem" do 422 não o traz);
com outro, o outro é devolvido (200) e o preso volta em
"refund.missing_amount", com esse motivo.
Repita-o com o mesmo "refund_amount" — a repetição usa a mesma chave, e
o provedor não devolve duas vezes — ou espere a confirmação; depois
devolva o que restar.
A CONTA QUE MUDOU DURANTE A EXCLUSÃO (entrou um pagamento enquanto ela
era excluída) não sai: 422 nao_foi_possivel com "reason": "mudou", e
nada muda. Leia a conta (GET) e decida de novo.
/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: o dia em que o dinheiro entrou (ou saiu).
Sem ele (ou null ou ""), hoje — no fuso do espaço (timezone do
GET /me). Pode ser antes do vencimento e antes da criação da
conta; não pode ser depois de hoje nem antes de 2000-01-01:
422 data_futura depois de hoje, no fuso do espaço
422 data_antiga antes de 2000-01-01 (ano digitado errado)
422 data_invalida fora do formato, não existe (2026-02-31)
ou não é texto (objeto, lista, número,
booleano)
paid_amount opcional, INTEIRO em centavos, de 0 a 999999999999 (R$ 150,00 =
15000; 15000, "15000" e 15000.0 valem). Negativo, fração, texto
que não é só dígitos ("150.00", "1e3"), booleano ou lista: 422
dados_invalidos com "field": "paid_amount" — nada é
arredondado. Sem ele, grava o valor DAQUELE DIA:
juros, multa e desconto das regras da conta calculados para o
settled_at — recebida no próprio vencimento, sem a multa. É o
mesmo número que a tela de baixa mostra para aquela data. Mande-o
quando o total recebido foi outro (negociação, desconto).
paid_amount é o TOTAL recebido na conta, incluindo o que já
entrou pelo pagamento online (o paid_amount que o GET mostra na
conta em aberto): para registrar só o resto, recebido à mão,
some os dois. Menos do que já entrou pelo provedor é 422
dados_invalidos com "field": "paid_amount" e
"online_paid_amount" (o que já entrou, em centavos), e nada é
gravado. Com outro valor que não o do dia, o detalhamento da
conta paga (a
fatura e o PDF) mostra o valor original e a diferença — a menos,
desconto; a mais, acréscimo —, sem os juros, a multa e o
desconto das regras, que não foram cobrados.
WARNINGS (só quando há): ["provider_payment_pending"] = a conta tinha um
pagamento em processamento no provedor (a cobrança automática no cartão do
cliente, ou um boleto gerado e ainda não pago) e a baixa valeu mesmo assim.
Confira no provedor: se aquele pagamento também entrar, ele fica no lugar
desta baixa e o dono recebe um aviso para devolver um dos dois.
SÓ CONTA EM ABERTO (pending ou overdue). Conta já quitada ou cancelada
responde 409, com a conta como ela está em "account":
{ "error": { "code": "ja_liquidada",
"message": "Esta conta já está quitada.",
"account": { "id": 1234, "status": "received",
"settled_at": "2026-07-09", "...": "..." } } }
409 ja_liquidada já está paga/recebida. A chamada REPETIDA (reenvio
depois de um timeout) cai aqui: a primeira valeu, e
"account" diz com que data. Antes, a repetição criava
um segundo pagamento.
409 conta_cancelada a conta está cancelada e não aceita baixa
Para mudar a data de uma baixa feita à mão, use PATCH com "settled_at".
/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 (o "refund", o
"refund_amount", o 409 exige_decisao_estorno e os motivos de recusa, logo
abaixo): sem "refund" no corpo, 409; "refund": true devolve ao cliente e
reabre; "refund": false só reabre na Pagsim. A devolução PARCIAL
("refund_amount" menor que o que resta) reabre a conta, e a fatura passa a
cobrar a diferença. Depois da devolução parcial, "paid_amount" é o que
ficou com o espaço.
Conta CANCELADA não reabre: 409 conta_cancelada, antes de qualquer
estorno. Se ela foi cancelada por outra chamada DEPOIS que a devolução
desta saiu (as duas ao mesmo tempo), o 409 conta_cancelada traz também
"refund" (a devolução feita, no mesmo formato do 200) e "account" (a
conta como ficou, cancelada): o valor voltou ao cliente — não devolva
de novo por fora.
/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", "status": "confirmed",
"refunds": [ { "module": "stripe", "amount": 15000, "currency": "BRL",
"external_id": "re_1abc", "status": "confirmed" } ],
"missing_amount": 0 } }
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,
"refundable_amount": 15000, "motivo": "" } }
"module" e "amount" são do pagamento que o Pagsim oferece primeiro: o
mais recente que dá para devolver; sem nenhum, o mais recente com
dinheiro que não se devolve pelo Pagsim, depois o contestado e, por
último, a cobrança que ainda espera a confirmação. "amount" é o valor
inteiro desse pagamento; "refundable_amount", o que AINDA pode ser
devolvido na CONTA INTEIRA: a soma dos pagamentos online dela que se
devolvem pelo Pagsim (a conta paga duas vezes, por exemplo), menos o que
já voltou ao cliente — menor depois de uma devolução parcial. O que não
se devolve por aqui, como o pagamento antigo da Adyen sem o identificador
ou o módulo sem estorno, fica fora e volta em "missing_amount" no
"refund": true; o pagamento com um pedido de devolução ainda sem
resposta (estorno_em_andamento, abaixo) também fica fora.
COBRANÇA À ESPERA AO LADO: se a conta tem, além do pagamento oferecido,
uma cobrança do provedor que ainda espera a confirmação (a renovação no
cartão, um boleto gerado), o "payment" traz também "pending_charge_amount"
(a soma dessas cobranças, em centavos) e "pending_charge_module" (o
provedor da mais recente). Os dois só vêm quando ela existe (no /cancel e
no /unsettle). Cancelar ou reabrir NÃO a interrompe: se ela for confirmada
depois, o dinheiro fica registrado na conta, para devolver.
Quando "refundable" é false, "motivo" diz por quê:
aguardando_confirmacao um pagamento iniciado no provedor (a cobrança
automática no cartão, um boleto gerado) ainda
espera a confirmação: o cliente pode não ter
pago (ainda)
sem_psp pagamento antigo da Adyen sem o identificador:
devolva pelo Customer Area da Adyen
contestado o cliente contestou e o banco dele já devolveu o
valor: não há o que devolver pelo Pagsim
provedor_sem_estorno o módulo não tem estorno pela API
estorno_em_andamento um pedido de devolução deste pagamento, de
outro valor, ainda não teve resposta do provedor
(a devolução parcial cuja resposta se perdeu, ou
que ele ainda não confirmou). Só neste caso vem
"pending_refund_amount", o valor do pedido:
repita-o com esse "refund_amount" (a repetição
usa a mesma chave e não devolve duas vezes) ou
espere a confirmação; até lá, o "refund": true
sem valor dá 422 estorno_falhou com esse motivo
(com outro pagamento livre na conta, devolve o
outro e o preso volta em "missing_amount")
Aí escolha: "refund": true devolve ao cliente tudo o que a conta tem para
devolver (cada pagamento online, um depois do outro); false cancela só no
Pagsim. Com false, a conta a receber cancelada fica com o pagamento
registrado e não se exclui (409 pagamento_a_devolver) até o pagamento ser
devolvido: pelo /cancel com "refund": true, ou pelo painel do provedor,
cujo aviso registra a devolução no Pagsim. Não é automático porque
devolver dinheiro é irreversível e a tarifa normalmente não volta junto.
"refund" aceita os sim/não desta API: true/false, 1/0, "1"/"0",
"true"/"false", "yes"/"no" e "on"/"off" (no texto, maiúsculas e espaços
nas pontas não importam). null ou "" é o mesmo que não mandar: 409
exige_decisao_estorno. Outro valor ("sim", 2) é 422 dados_invalidos com
"field": "refund", e nada muda.
"refund_amount" (opcional): a devolução PARCIAL, INTEIRO em centavos
(15000, "15000" ou 15000.0). Sem ele, devolve o "refundable_amount".
Com mais de um pagamento, o valor sai do mais recente para o mais antigo
— o pagamento preso a um pedido sem resposta fica por último, e o valor
IGUAL ao "pending_refund_amount" vai primeiro a ele (é a repetição do
pedido, com a mesma chave).
Fração, texto que não é só dígitos ("150.00"), booleano ou lista: 422
dados_invalidos com "field": "refund_amount", ANTES de pedir qualquer
coisa ao provedor. Zero, ou mais do que a soma do que resta em TODOS os
pagamentos da conta que se devolvem pelo Pagsim — o "refundable_amount"
mais o pagamento preso a um pedido sem resposta, que ele deixa de fora —:
422 estorno_falhou com "motivo": "valor_invalido", e nada muda. Acima do
"refundable_amount" e até essa soma, o valor NÃO é recusado: os
pagamentos livres são devolvidos primeiro (do mais recente ao mais
antigo) e o que passa deles é pedido ao preso, que só aceita a repetição
do mesmo pedido (o "pending_refund_amount"); com outro valor, a parte
dele falha e volta em "refund.missing_amount" com "motivo":
"estorno_em_andamento" (200, "warnings": ["refund_incomplete"]) — ou 422
estorno_falhou com esse motivo, se nada voltou. Para não devolver só uma
parte sem querer, mande no máximo o "refundable_amount", ou o
"pending_refund_amount" para repetir o pedido preso. A "mensagem" desse
motivo — a do 422 e a "refund.mensagem" do 200 — não traz o valor: ele
está no "pending_refund_amount" do 409 exige_decisao_estorno (e na
mensagem do 409 pagamento_a_devolver do DELETE).
"refund.status" é "confirmed", ou "pending" quando o provedor confirma a
devolução depois (a Adyen, sempre; o Pix do Inter, enquanto a devolução
está em processamento). No /unsettle, a confirmação, ou a recusa (a
conta volta a recebida), chega como receivable.updated no webhook. No
/cancel, a conta continua cancelada e nada muda nela: não há aviso no
webhook, e a recusa vai ao dono do espaço por e-mail e ao histórico.
"refund.amount" é o total devolvido agora; "refund.refunds", cada
devolução (uma por pagamento, com "module", "amount", "currency",
"external_id" e "status"). DEVOLUÇÃO QUE FICOU PELA METADE: se algum
pagamento voltou e outro não — o provedor recusou um deles, ou ele não
se devolve pela API (o pagamento antigo da Adyen sem o identificador, o
módulo sem estorno) —, a decisão vale: a conta é cancelada (ou
reaberta), o que voltou fica registrado, e a resposta traz
"refund.missing_amount" (o que ficou, em centavos), "refund.motivo" e
"refund.mensagem" (o código e o texto do primeiro que não voltou) e
"warnings": ["refund_incomplete"]. Na cancelada, o que ficou se devolve
com o /cancel e "refund": true de novo, ou pelo painel do provedor; na
reaberta, ele continua na conta como pagamento recebido ("paid_amount"),
e a fatura cobra só a diferença. Com "motivo": "estorno_em_andamento", o
pagamento que ficou tem um pedido de devolução ainda sem resposta do
provedor, e o "refund": true de novo dá 422 estorno_falhou até ela:
repita o pedido com o mesmo "refund_amount" (o "pending_refund_amount"
do 409) ou espere a confirmação. "missing_amount" é 0 quando tudo voltou.
CONTA JÁ CANCELADA que recebeu um pagamento depois (por exemplo, a
cobrança automática que estava em andamento): "refund": true devolve, e a
conta continua cancelada — não é cancelada de novo. Sem pagamento online,
chamar de novo numa cancelada responde 200 e não muda nada.
422 nao_foi_possivel, com "reason":
ocupada um pagamento ou uma baixa desta conta está sendo
gravado agora. Nada foi alterado nem devolvido,
inclusive com "refund": true (o Pagsim reserva a
conta ANTES de o dinheiro sair): tente de novo em
alguns segundos
devolvido_sem_cancelar o valor voltou ao cliente, mas o cancelamento
falhou depois. "refund" traz a devolução feita (o
mesmo formato do "refund" do 200) e "account", a
conta como ficou. Repita com "refund": false: com
o mesmo "refund_amount", a devolução sairia de novo
Se o provedor recusar o estorno — ou se o Pagsim não puder pedi-lo agora
(os motivos acima) —, 422 estorno_falhou e nada muda (é quando NADA
voltou ao cliente):
{ "error": { "code": "estorno_falhou",
"message": "Não foi possível estornar o pagamento; a conta não foi cancelada.",
"motivo": "moeda_casas",
"mensagem": "texto do motivo, para mostrar a alguém" } }
"motivo" é o código (estável, para o seu programa decidir); "mensagem", o
mesmo motivo em texto. Além dos do provedor e dos acima:
estorno_em_andamento (repita com o mesmo valor), estorno_ocupado (outra
devolução desta conta está sendo pedida agora: espere alguns segundos e
leia a conta antes de pedir de novo), estorno_nao_confirmado (a devolução
pedida antes não teve resposta, e o pedido foi encerrado sem pedir de
novo: confira no painel do provedor — o Customer Area da Adyen, o
Internet Banking do Inter — se ela saiu antes de pedir de novo; se não
saiu, o pedido seguinte é outra devolução), ja_devolvido (o provedor diz
que este pagamento já estava devolvido inteiro, por fora, e nada saiu
agora; o Pagsim o dá por devolvido e devolve o resto da conta pelos
outros pagamentos no mesmo pedido), devolucao_incompleta (o provedor
corrigiu, durante o pedido, quanto restava em mais de um pagamento, e
parte do valor não chegou a ser pedida: quando parte saiu (200), o que
não foi pedido está em "refund.missing_amount"; quando nada saiu, vem o 422
estorno_falhou com este motivo, sem "missing_amount" — nos dois, leia a
conta e peça de novo o resto), stripe_sem_faturas (a chave restrita da Stripe não lê
faturas: inclua "Invoices — read" e repita) e fatura_nao_encontrada (a
Stripe não achou a fatura deste pagamento com a chave do espaço: devolva
pelo painel da Stripe).
/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.
ESPAÇO ACIMA DO LIMITE DO PLANO: se a conta já tem o link pronto
(código, pin e link ativo), a rota continua respondendo 201 com o
mesmo link e não grava nada — o cliente ainda precisa pagar. Sem eles
(conta sem pin, ou com o link revogado), a rota gravaria e responde
403 limite_excedido até o espaço voltar ao limite. Veja Limites.
/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/{id}
rec ou pay (ver)
Uma régua, com o vencimento da próxima cobrança em aberto.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/recurrences/77
Resposta
{ "id": 77, "external_ref": "boffice-4711", "direction": "in",
"description": "Plano Pro", "amount": 9900, "freq": "monthly",
"start_date": "2026-09-10", "end_date": null, "occurrences": null,
"active": true, "itemized": false, "contact_id": 88, "category_id": 5,
"account_id": null, "ruleset_id": null, "index_id": null, "party": null,
"next_due_date": "2026-09-10" }
O mesmo objeto da lista e do POST. "next_due_date" é o vencimento da
próxima cobrança em aberto (null com a régua desligada ou sem cobrança
aberta a vencer). Numa régua de itens ("itemized": true), "amount" é zero:
o valor de cada cobrança é a soma dos itens dela.
Régua do lado que a chave não vê (a pagar sem pay, a receber sem rec):
404 not_found, como se não existisse.
/recurrences/ref:{sua_ref}
rec ou pay (ver)
A régua pela SUA referência (external_ref), sem guardar o id do Pagsim.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/recurrences/ref:boffice-4711
Resposta
{ "id": 77, "external_ref": "boffice-4711", "direction": "in", ... }
O ATALHO ref:{sua_ref} vale no lugar do id em todas as rotas de uma régua:
GET, PATCH e DELETE /recurrences/ref:boffice-4711, e as de itens
(…/ref:boffice-4711/items, …/ref:boffice-4711/item-templates). É o mesmo
atalho de /subscriptions/ref:. Referência que não existe neste espaço: 404
not_found.
/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.
"has_consumption" é true ou false (também 1/0 e "true"/"false"): true
cria a série de itens (o valor de cada cobrança é a soma dos itens);
false, "false" ou ausente, a série de valor fixo, com o "amount" (que
então não pode ser 0). Outro valor é 422 campo_invalido com "field":
"has_consumption", e nada é criado.
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.
O TIPO também não: "has_consumption" no corpo é ignorado (a série de
valor fixo continua de valor fixo, e o "amount" dela não pode ser 0).
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.
Desligar também cancela a assinatura no provedor que agenda as cobranças
(Stripe), como o /subscriptions/{id}/cancel; se o provedor não confirmar,
o Pagsim tenta de novo e avisa o dono nas pendências.
Numa régua JÁ DESLIGADA — por você, ou pelo sistema (o espaço em atraso
com a Pagsim tem as réguas desligadas, e a assinatura no provedor fica
como estava) —, o DELETE é o encerramento do mesmo jeito: cancela no
provedor a assinatura que ainda estiver ativa, e a régua continua
desligada (não religa). Chamar de novo não faz mais nada (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. Também vale no corpo, como true ou false; no corpo, outro valor é
422 campo_invalido, e nada muda.
/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 }
Cada item é o objeto inteiro de GET /subscriptions/{id}. Só as réguas A
RECEBER são assinaturas (o cliente paga o espaço); as a pagar ficam em
/recurrences.
/subscriptions/{id}
rec (ver)
O estado de uma assinatura pelo id da régua.
Requisição
curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/subscriptions/77
Resposta
{ "id": 77, "status": "active", "active": true,
"description": "Plano Pro", "amount": 9900, "frequency": "monthly",
"started_on": "2026-09-10", "ends_on": null, "external_ref": "boffice-4711",
"contact": { "id": 88, "name": "Fulano de Tal", "email": "fulano@exemplo.com" },
"paid_through": "2026-10-10",
"last_payment": { "id": 1250, "due_date": "2026-10-10",
"settled_at": "2026-10-09", "amount": 9900 },
"next_charge": { "id": 1251, "due_date": "2026-11-10", "amount": 9900 },
"days_late": 0, "grace_days": 7 }
O id é o da régua (o mesmo de /recurrences). "frequency" aqui é o "freq" da
régua (os mesmos valores). "paid_through" é o vencimento da última
cobrança paga; "last_payment" e "next_charge" são null quando não há.
"days_late" conta os dias desde o vencimento da cobrança em aberto mais
antiga; "grace_days" é a carência que o Pagsim dá antes de past_due virar
expired. "contact" é null sem contato ligado.
O "contact.email" só vem para a chave com contacts (ver) — sem essa
permissão vem null, como em toda a API, que só mostra dado de contato a
quem vê contatos (confira com POST /permissions/check). Vale para a lista,
para o ref: e para o cancel e o reactivate.
Só as réguas a receber: uma régua a pagar não é assinatura, e o id dela
aqui responde 404 not_found.
/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, "status": "active", "active": true,
"description": "Plano Pro", "amount": 9900, "frequency": "monthly",
"started_on": "2026-09-10", "ends_on": null, "external_ref": "boffice-4711",
"contact": { "id": 88, "name": "Fulano de Tal", "email": "fulano@exemplo.com" },
"paid_through": "2026-10-10",
"last_payment": { "id": 1250, "due_date": "2026-10-10",
"settled_at": "2026-10-09", "amount": 9900 },
"next_charge": { "id": 1251, "due_date": "2026-11-10", "amount": 9900 },
"days_late": 0, "grace_days": 7 }
O mesmo objeto de GET /subscriptions/{id}.
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, "provider_subscription": "none" }
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. A que tem uma cobrança
automática em processamento no cartão do cliente, ou um boleto gerado e
ainda não pago, fica (o pagamento que chegasse ficaria sem conta); também
fica a que já recebeu parte do pagamento pelo provedor.
"keep_open_charges" é true ou false (também "true"/"false"); outro valor é
422 campo_invalido, e nada é cancelado.
A ASSINATURA NO PROVEDOR que agenda as cobranças (Stripe; Cielo nas
antigas) é cancelada junto: "provider_subscription" = "canceled". Quando o
provedor não confirma, "pending": a régua já está encerrada aqui, o Pagsim
tenta de novo nas rodadas seguintes e avisa o dono nas pendências. "none":
não havia assinatura no provedor (a renovação no cartão da Adyen é do
próprio Pagsim e para junto).
/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 }
Religar NÃO recria a assinatura no provedor (Stripe): o cliente assina de
novo pela fatura.
/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 }
ARQUIVO RECUSADO: 422 nao_foi_possivel com "reason" e a mensagem do motivo.
"many" — a conta já chegou ao máximo de arquivos por conta; traz "limit".
É o do plano (apague um anexo ou assine um plano maior) ou, se
for menor, o teto do Pagsim por conta (aí só apagando).
"big" — o arquivo passa do tamanho máximo; traz "max_bytes" (o menor
entre o limite do Pagsim, 8 MB, e o do servidor). Vale também
para o envio tão grande que o servidor descarta o corpo inteiro.
"type" — tipo não aceito. Aceitos: PDF, JPG, PNG, WEBP, DOC e DOCX; o tipo
é lido do conteúdo do arquivo, não do nome.
"fail" — o envio chegou incompleto ou não pôde ser guardado: envie de novo.
{ "error": { "code": "nao_foi_possivel", "reason": "many", "limit": 5,
"message": "Esta conta já chegou ao máximo de 5 arquivos permitido pelo plano. Apague um anexo ou assine um plano maior para anexar outro." } }
Plano sem anexos: 403 plano_nao_permite (veja "features" em /me). Espaço
acima de um limite do plano: 403 limite_excedido (veja Limites).
/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: no número de contatos que o plano permite, 403
limite_do_plano com "limit" e "used" (quantos o espaço já tem), e a
mensagem diz o que fazer:
{ "error": { "code": "limite_do_plano", "limit": 100, "used": 100,
"message": "O plano deste espaço permite até 100 contatos, e o espaço já tem 100. Apague um contato ou assine um plano maior para criar outro." } }
Espaço que JÁ PASSOU do limite (desceu de plano) recebe antes o 403
limite_excedido (veja Limites).
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.
Arquivo recusado: o mesmo 422 nao_foi_possivel das contas ("many" com
"limit" — o máximo de arquivos por contato do plano —, "big" com
"max_bytes", "type" e "fail"), com a mensagem do motivo.
/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): não cabe mais um. Traz "limit" (e "used" no POST /contacts). |
| 403 | limite_excedido | O espaço JÁ PASSOU de um limite do plano (ex.: desceu de plano): criar e editar estão suspensos até apagar ou assinar um plano maior. Apagar, dar baixa, cancelar, pedir a nota, cancelar assinatura e o payment-link de uma conta com o link já pronto seguem liberados. Traz "limits": [{limit, used, allowed, to_remove, records?}]. Veja Limites. |
| 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); null ou "" contam como não informado. Traz o pagamento em "payment", com "refundable_amount" e, quando não dá para devolver, o "motivo". O "refundable_amount" é o da conta inteira: a soma dos pagamentos online que se devolvem pelo Pagsim agora (com um pedido de devolução sem resposta, "motivo" estorno_em_andamento e "pending_refund_amount"). Com uma cobrança do provedor à espera da confirmação na conta, também "pending_charge_amount" e "pending_charge_module". |
| 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". |
| 409 | ja_liquidada | Baixa numa conta já quitada (inclui a chamada repetida). Traz a conta em "account". |
| 409 | conta_cancelada | Baixa, reabertura ou nova data de pagamento numa conta cancelada. No /unsettle cuja devolução já saiu quando a conta foi cancelada por outra chamada, traz "refund" e "account". |
| 409 | conta_em_aberto | PATCH settled_at numa conta que não está paga: use POST .../settle. |
| 409 | pago_online | PATCH settled_at numa conta paga pelo provedor: a data vem dele. Traz "module" (e "provider_date" na baixa antiga gravada no dia UTC: só esse dia é aceito). |
| 409 | pagamento_em_processamento | Exclusão de conta com pagamento em processamento no provedor (a cobrança automática no cartão, um boleto gerado e não pago) ou com pagamento pelo banco em andamento. Na conta a receber: cancele a conta ou espere a confirmação. Na conta a pagar: cancele o pagamento pelo banco no painel ou espere o banco concluí-lo (cancelar a conta não o cancela). |
| 409 | pagamento_a_devolver | Exclusão de conta a receber cancelada com um pagamento do provedor que não foi devolvido (o que entrou depois de cancelada, ou o da conta cancelada com "refund": false): devolva antes (POST .../cancel com "refund": true; se a devolução já foi pedida, espere a confirmação do provedor; se o pagamento não se devolve pela API, devolva pelo painel do provedor). Com um pedido de devolução parcial sem resposta, a mensagem diz o "refund_amount" para repeti-lo. |
| 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 e /subscriptions. Veja "field". |
| 422 | data_invalida | Data fora do formato YYYY-MM-DD, que não existe, ou valor que não é texto. Veja "field". |
| 422 | data_futura | Data de pagamento depois de hoje, no fuso do espaço. Veja "field". |
| 422 | data_antiga | Data de pagamento antes de 2000-01-01 (ano digitado errado). 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" (na exclusão, "mudou": entrou um pagamento durante a exclusão — leia a conta e decida de novo; no /cancel, "ocupada": a conta está sendo gravada e nada mudou nem foi devolvido — tente de novo em segundos —, ou "devolvido_sem_cancelar": o valor voltou ao cliente mas a conta não foi cancelada; traz "refund" e "account", e a repetição é com "refund": false). |
| 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 módulo do pagamento não tem estorno pela API (devolva pelo painel do provedor). |
| 422 | estorno_falhou | O estorno foi recusado, ou não pode ser pedido agora (aguardando_confirmacao, sem_psp, contestado, estorno_ocupado...); nada foi alterado. "motivo" traz o código; "mensagem", o texto. |
| 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.
403 limite_excedidoO plano limita o que o espaço guarda: pessoas na equipe (team), categorias
(categories), contas e carteiras (accounts), contatos
(contacts), campos de contato (contact_fields), campos de conta
(transaction_fields), arquivos por conta (files_per_transaction) e
arquivos por contato (files_per_contact) — e os lançamentos que vencem no mês
(transactions_month, abaixo). Quando o espaço já passou de um
deles — desceu de plano, voltou ao grátis —, criar e editar ficam suspensos, no painel e
aqui, até apagar o que passou ou assinar um plano maior. A trava some sozinha no instante
em que o uso volta a caber.
É diferente do limite_do_plano: aquele diz que não cabe mais um (o
101º contato); este diz que o espaço já está acima, e vale para toda escrita.
HTTP/1.1 403
{ "error": { "code": "limite_excedido",
"message": "O espaço passou do limite do plano Básico (categorias: 12 de 10). Criar e editar estão suspensos até apagar registros ou assinar um plano maior; apagar continua liberado.",
"limits": [ { "limit": "categories", "used": 12, "allowed": 10, "to_remove": 2 },
{ "limit": "files_per_transaction", "used": 5, "allowed": 2,
"to_remove": 4, "records": 3 } ] } }
Nos limites por registro (files_per_*), used é o maior número
num registro, records quantos registros passam e to_remove quantos
arquivos apagar no total.
Continuam liberados: todo DELETE, POST /{receivables|payables}/{id}/settle,
…/cancel, POST /receivables/{id}/nfse e
POST /subscriptions/{id}/cancel — apagar e as obrigações já em curso —, e o
POST /receivables/{id}/payment-link de uma conta que já tem o link pronto (código,
pin e link ativo): a rota só devolve o que existe, e o cliente ainda precisa pagar. Gerar um
link novo (a conta sem pin ou com o link revogado) continua barrado. Os
GET nunca são barrados. Barrados: os POST que criam, todo
PATCH/PUT, unsettle, o payment-link que
gravaria, comentários, anexos, itens e reactivate. O somente_leitura vem antes
deste. Para saber antes de tentar, leia over_limit no GET /me; o
/permissions/check confere só as permissões, não esta trava.
Os lançamentos que vencem no mês corrente também entram (transactions_month)
quando passam do limite do plano atual — só acontece depois de descer de plano, porque a cota
não deixa passar dele: o lançamento além dele é recusado com 422 dados_invalidos e
"field": "quota" (veja POST /receivables). Destrava ao apagar
lançamentos que vencem neste mês, na virada do mês ou ao subir de plano. As consultas por mês
não entram.
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 — inclusive a devolução, a contestação e a renovação
no cartão confirmadas pelo provedor — 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.