API da Pagsim

Versão v1 · base https://pagsim.com/api/v1

Autenticação

Toda chamada (menos GET /) precisa do cabeçalho:

Authorization: Bearer psk_...

A chave é gerada no painel: o titular do espaço, em Ajustes → Chave de API; quem é da equipe, no item Chave de API do menu. Ela vale para um espaço só e age como a pessoa que a criou: tudo que ela não pode fazer no painel, a chave também não faz — cada pessoa tem a sua, com as permissões que o titular marcou para ela em Ajustes → Equipe.

A chave para de funcionar sozinha, sem ninguém precisar revogá-la, quando a pessoa sai da equipe, quando a conta dela é suspensa, quando o espaço é arquivado, excluído ou fica com a assinatura vencida, e quando o plano do espaço deixa de incluir API. Os códigos de cada caso estão em Erros.

Comece pelo /me. Ele confirma a chave, mostra o espaço e lista as permissões — numa chamada só, sem tocar em dado nenhum. Quem começa por /receivables descobre três problemas possíveis ao mesmo tempo e não sabe qual é.

curl -H "Authorization: Bearer psk_..." \
  https://pagsim.com/api/v1/me
{
  "space": { "id": 12, "name": "Minha empresa", "currency": "BRL",
             "timezone": "America/Sao_Paulo",
             "invoice_host": "pagar.minhaempresa.com.br" },
  "permissions": {
    "receivables": 2, "payables": 1, "contacts": 2,
    "files_rec": 2, "files_pay": 0, "files_contacts": 1,
    "comment_rec": 2, "comment_pay": 0, "comment_contacts": 1,
    "consumption_rec": 2, "consumption_pay": 0,
    "nfse": 1,
    "owner": false
  },
  "permission_levels": ["nenhum", "ver", "gerenciar"],
  "features": { "payment_link": true, "attachments": true,
                "contact_attachments": true, "custom_domain": true,
                "nfse": true }
}

Antes de ir para produção: confira a chave

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.

Formatos e convenções

Dinheiro em centavos, sempre

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.

Datas

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.

O que NÃO sai pela API

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.

Nota fiscal: sempre a partir de uma conta

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.

Corpo em JSON

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".

Rotas

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.

Início

GET /

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"
}
GET /me

O espaço da chave e AS PERMISSÕES dela. Comece por aqui.

Requisição

curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/me

Resposta

{
  "space": { "id": 12, "name": "Minha empresa", "currency": "BRL",
             "timezone": "America/Sao_Paulo",
             "invoice_host": "pagar.minhaempresa.com.br" },
  "permissions": {
    "receivables": 2, "payables": 1, "contacts": 2,
    "files_rec": 2, "files_pay": 0, "files_contacts": 1,
    "comment_rec": 2, "comment_pay": 0, "comment_contacts": 1,
    "consumption_rec": 2, "consumption_pay": 0,
    "nfse": 1,
    "owner": false
  },
  "permission_levels": ["nenhum", "ver", "gerenciar"],
  "features": { "payment_link": true, "attachments": true,
                "contact_attachments": true, "custom_domain": true,
                "nfse": true }
}

AS PERMISSÕES SÃO AS DO PAINEL, da pessoa que criou a chave — as mesmas
que o dono do espaço marcou para ela em Ajustes → Equipe. Cada rota abaixo
diz qual exige; sem ela, a resposta é 403 sem_permissao.

  receivables / payables   ver e gerenciar contas a receber / a pagar
  contacts                 ver e gerenciar contatos
  files_*                  anexos daquela área (ver/baixar · enviar/apagar —
                           apagar só os próprios, exceto o titular)
  comment_*                comentários daquela área (escrever exige 2)
  consumption_*            lançar itens de consumo naquela área (exige 2)
  nfse                     nota fiscal: 1 lista, lê e baixa as notas;
                           2 pede a nota de uma conta (com receivables ver)
  owner                    titular ou administrador: tudo

FEATURES diz o que o PLANO do espaço inclui entre o que a API oferece —
sem payment_link, POST .../payment-link responde 403 plano_nao_permite.
custom_domain é true quando os links da fatura saem no DOMÍNIO PRÓPRIO do
espaço (o plano inclui e o domínio já está ativo). nfse é a nota fiscal:
sem ela, toda rota de /nfse e POST /receivables/{id}/nfse respondem 403
plano_nao_permite — ler e baixar também.

INVOICE_HOST é o endereço em que os links da fatura deste espaço abrem
agora: o domínio próprio, quando custom_domain é true; senão, o da Pagsim.
Não monte o link com um endereço fixo no seu código — use o "invoice_url"
das contas, ou este host.

Para conferir de uma vez se a chave tem TUDO o que a sua integração usa,
veja POST /permissions/check, logo abaixo.

O TIMEZONE é o do espaço, e importa para quem compara datas.

As datas da API — due_date, happened_on, settled_at — são datas de
calendário, sem hora e sem fuso: "2026-09-10" é o dia 10, aqui e em
qualquer lugar. O fuso NÃO as desloca.

Ele importa para saber que dia é "hoje" para este espaço. O que decide se
uma conta está vencida, ou qual cobrança recebe um item novo, é o dia
corrente do espaço — não o do seu servidor. Um servidor em UTC às 22h de
São Paulo já virou o dia; usar a data dele faria uma conta parecer vencida
antes da hora.

Leia o timezone uma vez e calcule "hoje" com ele antes de comparar
qualquer due_date.

Os campos com HORA — created_at, updated_at, url_expires_at — vêm em UTC,
no formato ISO 8601 com Z no fim. Converta para exibir.
POST /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.
GET /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; }

Contas a receber

GET /receivables rec (ver)

Lista, com filtros e paginação.

Requisição

curl -H "Authorization: Bearer psk_..." \
  "https://pagsim.com/api/v1/receivables?status=pending&per_page=2"

Resposta

{
  "data": [
    {
      "id": 1234,
      "direction": "in",
      "description": "Mensalidade de julho",
      "amount": 15000,
      "paid_amount": null,
      "currency": "BRL",
      "due_date": "2026-07-10",
      "status": "pending",
      "settled_at": null,
      "category": { "id": 5, "name": "Serviços" },
      "account":  { "id": 2, "name": "Banco Inter" },
      "contact":  { "id": 88, "name": "Fulano" },
      "party": null,
      "has_items": false,
      "invoice_code": "26-K7M2XQ",
      "invoice_url": "https://pagar.minhaempresa.com.br/26-K7M2XQ",
      "recurrence_id": null,
      "created_at": "2026-06-28T11:02:00Z",
      "updated_at": "2026-06-28T11:02:00Z",
      "nfse": { "id": 55, "status": "emitida", "number": "1007" }
    }
  ],
  "meta": { "total": 137, "page": 1, "per_page": 2, "total_pages": 69 }
}

Filtros na seção "Filtros e paginação", mais abaixo. A busca "q" é a mesma
da tela: descrição e nome da outra parte sem diferença de acento ("agua"
acha "Água") e o número da fatura, inteiro ou só a parte depois do traço.

NFSE é o resumo da NOTA FISCAL da conta — id, situação e número oficial —,
a mesma nota que a tela da conta mostra: a que está viva (na fila,
enviada, emitida, em cancelamento, ou parada com erro depois de um envio
sem resposta) ou, sem nenhuma viva, a mais recente. Vem null quando a conta
não tem nota e também quando a chave não vê notas (sem a permissão nfse,
ou plano sem nota fiscal) — o resto da conta sai do mesmo jeito. A nota
inteira está em GET /nfse/{id}. O mesmo "nfse" volta em todas as rotas que
devolvem a conta (criar, alterar, baixar, reabrir, cancelar).

INVOICE_URL é o link da fatura para mandar ao cliente, JÁ NO DOMÍNIO
PRÓPRIO do espaço quando ele tem um ativo e o plano inclui domínio próprio
(o mesmo endereço do painel e do e-mail da fatura); senão, no endereço da
Pagsim. Vem null nos mesmos casos em que o painel não mostra o link: conta
a pagar, link ainda não gerado (ou revogado no painel) e plano sem link de
fatura. Não traz o pin — o pin sai só em
POST /receivables/{id}/payment-link, que também gera o link quando ele
ainda não existe.
GET /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)".
POST /receivables rec (gerenciar)

Cria uma conta. `direction` vem da rota e é ignorado no corpo.

Requisição

curl -X POST https://pagsim.com/api/v1/receivables \
  -H "Authorization: Bearer psk_..." \
  -H "Content-Type: application/json" \
  -d '{
        "description": "Mensalidade de julho",
        "amount": 15000,
        "due_date": "2026-07-10",
        "contact_id": 88,
        "category_id": 5,
        "account_id": 2
      }'

Resposta

201 Created

{
  "id": 1234,
  "direction": "in",
  "description": "Mensalidade de julho",
  "amount": 15000,
  "currency": "BRL",
  "due_date": "2026-07-10",
  "status": "pending",
  "category": { "id": 5, "name": "Serviços" },
  "contact":  { "id": 88, "name": "Fulano" }
}

OS CAMPOS são os do formulário do painel:

  description    obrigatória
  amount         obrigatório, em centavos
  due_date       obrigatório, YYYY-MM-DD
  category_id, account_id, contact_id   opcionais — ids DESTE espaço
  party          nome da outra parte, em texto (quando não há contato)
  notes          observação
  ruleset_id     juros/multa/desconto (GET /rulesets) — SÓ a receber
  index_id       índice de correção (GET /indices) — SÓ a receber
  settled        true = a conta já nasce paga/recebida, na data do vencimento
  has_consumption  1 = CONTA DE ITENS: exige também consumption_rec
                 (ou consumption_pay) gerenciar; nasce com valor 0 e sem
                 categoria — o valor passa a ser a soma dos itens (/items)

Um id de categoria, conta, contato, juros ou índice que não seja deste
espaço é recusado: 422 com "field" apontando o campo. Índice ARQUIVADO
também é recusado ao ligar uma conta a ele — a conta que já estava nele
continua aceitando as outras alterações. Numa conta a pagar,
ruleset_id e index_id são ignorados — juros de conta a pagar quem define é
o credor, e o painel faz o mesmo.

VINCULAR UM CONTATO (contact_id) exige também contacts (ver) — no painel,
quem não vê contatos não tem o seletor. Sem essa permissão a resposta é
403 sem_permissao; mandar o mesmo contato que a conta já tem, ou null para
desligar, continua valendo.

Erro de validação: 422 dados_invalidos com "field" (amount, due_date,
description, category_id... ou "quota", quando o limite de lançamentos do
plano para aquele mês acabou).
PATCH /receivables/{id} rec (gerenciar)

Altera SÓ os campos enviados. O resto fica como está.

Requisição

curl -X PATCH https://pagsim.com/api/v1/receivables/1234 \
  -H "Authorization: Bearer psk_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 18000 }'

Resposta

{
  "id": 1234,
  "description": "Mensalidade de julho",
  "amount": 18000,
  "due_date": "2026-07-10",
  "status": "pending"
}

Aceita: description, amount, due_date, category_id, account_id, party,
contact_id, notes, ruleset_id e index_id (os dois últimos só a receber).
Trocar o contact_id por outro contato exige contacts (ver), como no POST.

A DIREÇÃO NÃO MUDA — nem no painel. Quem errou o lado apaga e cria de novo.

CONTA DE ITENS: amount e category_id não se alteram (o valor é a soma dos
itens e a categoria é de cada item). Mandá-los com um valor DIFERENTE do
atual responde 422 conta_de_itens; o mesmo valor de volta é aceito.

Numa conta já baixada, alterar o valor redefine o recebido — a mesma regra
da tela.
DELETE /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 }
POST /receivables/{id}/settle rec (gerenciar)

Dá baixa. Corpo opcional.

Requisição

curl -X POST https://pagsim.com/api/v1/receivables/1234/settle \
  -H "Authorization: Bearer psk_..." \
  -H "Content-Type: application/json" \
  -d '{ "settled_at": "2026-07-09", "paid_amount": 15000 }'

Resposta

{
  "id": 1234,
  "amount": 15000,
  "paid_amount": 15000,
  "status": "received",
  "settled_at": "2026-07-09"
}

settled_at  opcional, YYYY-MM-DD. Sem ele, hoje — no fuso do espaço.
            Data que não existe (2026-02-31) responde 422 data_invalida.
paid_amount opcional, em centavos. Sem ele, grava o valor DO DIA, já com
            juros, multa e desconto das regras da conta — o mesmo número
            que a tela de baixa mostra. Mande-o quando entrou outro valor
            (pagamento parcial, negociação).
POST /receivables/{id}/unsettle rec (gerenciar)

Reabre a conta.

Requisição

curl -X POST https://pagsim.com/api/v1/receivables/1234/unsettle \
  -H "Authorization: Bearer psk_..."

Resposta

{ "id": 1234, "status": "pending", "paid_amount": null, "settled_at": null }

Se a conta foi paga ONLINE, vale a mesma decisão do /cancel: sem "refund"
no corpo, 409 exige_decisao_estorno; "refund": true devolve ao cliente e
reabre; "refund": false só reabre na Pagsim.
POST /receivables/{id}/cancel rec (gerenciar)

Cancela. Se houver pagamento online, exige decidir sobre o estorno.

Requisição

curl -X POST https://pagsim.com/api/v1/receivables/1234/cancel \
  -H "Authorization: Bearer psk_..." \
  -H "Content-Type: application/json" \
  -d '{ "refund": true }'

Resposta

{ "id": 1234, "status": "cancelled",
  "refund": { "amount": 15000, "external_id": "re_1abc" } }

Se a conta foi paga online e o corpo NÃO traz "refund", vem 409:

{ "code": "exige_decisao_estorno",
  "payment": { "module": "stripe", "amount": 15000,
               "currency": "BRL", "refundable": true } }

Aí escolha: "refund": true devolve ao cliente; false cancela só no
Pagsim. Não é automático porque devolver dinheiro é irreversível e a
tarifa normalmente não volta junto. Aceita "refund_amount" em centavos
para devolução parcial.
POST /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.

Contas a pagar

— /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 }
}

Itens de consumo

GET /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}.)
POST /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
DELETE /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.

Recorrências (a régua)

GET /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.
POST /recurrences rec ou pay (gerenciar)

Cria a régua e já gera as primeiras cobranças.

Requisição

curl -X POST https://pagsim.com/api/v1/recurrences \
  -H "Authorization: Bearer psk_..." \
  -H "Content-Type: application/json" \
  -d '{
        "external_ref": "boffice-4711",
        "description": "Plano Pro",
        "amount": 9900,
        "freq": "monthly",
        "start_date": "2026-09-10",
        "contact_id": 88,
        "category_id": 5
      }'

Resposta

201 Created

{ "id": 77, "external_ref": "boffice-4711", "amount": 9900,
  "freq": "monthly", "active": true, "itemized": false,
  "next_due_date": "2026-09-10" }

409 se a external_ref já existe — a resposta traz o recurrence_id de quem a tem.

ITENS JUNTO, numa transação só. Em série de itens ("has_consumption": 1),
o corpo aceita "items": [...] e a régua nasce com o plano dentro:

  { "description": "Assinatura", "amount": 0, "freq": "monthly",
    "start_date": "2026-09-10", "contact_id": 88,
    "has_consumption": 1,
    "items": [ { "description": "Mensalidade Pro",
                 "amount": 9900, "category_id": 5 } ] }

Assim não há janela entre criar a régua e mandar o modelo — nessa fresta o
cron poderia passar e gerar uma cobrança vazia. Os modelos são gravados
ANTES da materialização, então já valem na primeira cobrança.

Item inválido recusa a chamada inteira: nenhuma régua é criada. Ou vale
tudo, ou não vale nada.

CAMPOS: description, amount (centavos), freq (weekly, biweekly, monthly,
quarterly, semiannual, annual), start_date, e opcionais end_date,
occurrences, contact_id, category_id, account_id, party, ruleset_id,
index_id, external_ref, has_consumption e items. O contact_id exige
contacts (ver), como nas contas.

direction: "in" (padrão, a receber) ou "out" (a pagar). Decide a
permissão: régua a pagar exige pay (gerenciar). Juros e índice só valem a
receber — numa régua a pagar são ignorados, como no painel.

Série de itens (has_consumption ou items) exige também consumption_rec
(ou consumption_pay) gerenciar — a mesma permissão que o painel pede.

Ids de contato, categoria, conta, juros ou índice que não sejam deste
espaço: 422 campo_invalido com "field".
PATCH /recurrences/{id} rec ou pay (gerenciar)

Troca de plano. Só os campos enviados mudam.

Requisição

curl -X PATCH https://pagsim.com/api/v1/recurrences/77 \
  -H "Authorization: Bearer psk_..." \
  -H "Content-Type: application/json" \
  -d '{ "amount": 19900 }'

Resposta

{ "id": 77, "amount": 19900, "charges_updated": 6 }

charges_updated = quantas cobranças JÁ GERADAS receberam o valor novo.
O cron materializa ~190 dias à frente, então mexer só na régua faria o
plano novo valer daqui a meio ano. Vencidas e pagas ficam como estão.

effective_from (opcional, YYYY-MM-DD) muda o corte das cobranças alcançadas.

A DIREÇÃO NÃO MUDA depois de criada — "direction" no corpo é ignorado.

Trocar o contact_id por outro contato exige contacts (ver), como no POST.
DELETE /recurrences/{id} rec ou pay (gerenciar)

Desliga a régua. As cobranças geradas continuam.

Requisição

curl -X DELETE https://pagsim.com/api/v1/recurrences/77 -H "Authorization: Bearer psk_..."

Resposta

{ "id": 77, "active": false }

Para remover também as cobranças pendentes, use /subscriptions/{id}/cancel.

Chamar de novo numa régua já desligada não faz nada — ela continua
desligada (reenviar depois de uma queda de rede é seguro). Para religar,
POST /subscriptions/{id}/reactivate.
GET /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 }
POST /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.
GET /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.
POST /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.
PATCH /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.
DELETE /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.
DELETE /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.

Assinaturas (o estado)

GET /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 }
GET /subscriptions/ref:{sua_ref} rec (ver)

Busca pela SUA referência, sem tabela de-para.

Requisição

curl -H "Authorization: Bearer psk_..." https://pagsim.com/api/v1/subscriptions/ref:boffice-4711

Resposta

{ "id": 77, "external_ref": "boffice-4711", "status": "active",
  "active": true, "days_late": 0 }

active é o booleano que decide liberar acesso.
status detalha o porquê: active, past_due, expired, cancelled.
POST /subscriptions/{id}/cancel rec (gerenciar)

Cancela. Remove pendentes ainda não vencidas.

Requisição

curl -X POST https://pagsim.com/api/v1/subscriptions/77/cancel \
  -H "Authorization: Bearer psk_..." \
  -H "Content-Type: application/json" \
  -d '{ "keep_open_charges": false }'

Resposta

{ "id": 77, "status": "cancelled", "active": false,
  "future_charges_removed": 5 }

Cobranças VENCIDAS não são removidas: são dívida. As pendentes ainda não
vencidas saem (a menos que venha "keep_open_charges": true), cada uma com o
seu aviso "receivable.deleted" no webhook.
POST /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 }

Anexos

GET /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.
POST /receivables/{id}/attachments files_rec (gerenciar)

Envia um arquivo. multipart/form-data, campo "file".

Requisição

curl -X POST https://pagsim.com/api/v1/receivables/1234/attachments \
  -H "Authorization: Bearer psk_..." \
  -F "file=@nota-fiscal.pdf"

Resposta

201 Created

{ "id": 78 }

O limite de arquivos por conta é o do plano; passou, 422 com "reason": "many".
Plano sem anexos: 403 plano_nao_permite (veja "features" em /me).
Tamanho e tipo de arquivo seguem as mesmas regras da tela.
DELETE /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.
GET /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" } ] }
DELETE /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.

Comentários

POST /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 }

Contatos

GET /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.
GET /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).
POST /contacts contacts (gerenciar)

Cria um contato.

Requisição

curl -X POST https://pagsim.com/api/v1/contacts \
  -H "Authorization: Bearer psk_..." \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Fulano de Tal",
        "email": "fulano@exemplo.com",
        "country": "BR",
        "doc": "12345678900",
        "doc_type": "cpf",
        "kind_ids": [1, 2]
      }'

Resposta

201 Created

{
  "id": 88,
  "name": "Fulano de Tal",
  "email": "fulano@exemplo.com",
  "kind": { "id": 1, "name": "Cliente" },
  "kinds": [ { "id": 1, "name": "Cliente" }, { "id": 2, "name": "Fornecedor" } ]
}

OS CAMPOS são os da ficha do painel, com os MESMOS nomes da leitura:
name (obrigatório), email, phone, phone_ddi, country (padrão BR), doc,
doc_type, notes, kind_ids (lista) ou kind_id (um só), e os da aba de
dados fiscais: fiscal_kind (individual | company), legal_name, im, zip,
street, number, complement, district, city, state.

O documento é conferido como na tela (CPF/CNPJ com dígito verificador).
Erros vêm POR CAMPO: 422 dados_invalidos com "fields": { "doc": "..." }.

LIMITE DO PLANO: passou do número de contatos que o plano permite, 403
limite_do_plano com "limit".

CAMPOS PERSONALIZADOS ainda não são gravados pela API (a leitura vem em
"custom_fields"). Se o espaço tiver campo obrigatório, o contato criado
pela API nasce com "incomplete": true — o mesmo que a tela faz com a
criação rápida — e aparece no filtro de pendentes para a equipe completar.
PATCH /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.
DELETE /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.
POST /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.
POST /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.

Nota fiscal (NFS-e)

GET /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.
GET /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.
GET /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.
GET /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.
POST /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.

Apoio

GET /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" }
  ]
}
GET /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" }
  ]
}
GET /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" } ] }
GET /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.
GET /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.
GET /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.

Exemplo: criar e dar baixa

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 }'

Anexos

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"

Filtros e paginação

ParâmetroValores
statuspending, overdue, paid, received, cancelled
due_fromAAAA-MM-DD — vencimento a partir de
due_toAAAA-MM-DD — vencimento até
contact_idsó de um contato
category_idsó de uma categoria
account_idsó de uma conta
recurrence_idsó as cobranças geradas por uma recorrência
qa busca da tela: descrição e nome da outra parte, sem diferença de acento, e o número da fatura
updated_sincedata ou instante ISO — só o que mudou depois disso
pagea partir de 1
per_pagepadrã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.

Erros

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": "..." } }
HTTPcodeQuando
400json_invalidoO corpo não é um objeto JSON válido.
400sem_arquivoEnvio de anexo sem o campo "file" (multipart/form-data).
401sem_credencialFalta o cabeçalho Authorization.
401credencial_invalidaChave inválida, revogada, ou de uma conta suspensa.
403sem_acessoA pessoa da chave não faz mais parte do espaço (removida, ou convite não aceito).
403espaco_arquivadoO espaço foi arquivado ou excluído.
403espaco_bloqueadoAssinatura vencida ou espaço bloqueado.
403plano_sem_apiO plano do espaço não inclui acesso à API.
403sem_permissaoA pessoa da chave não tem essa permissão no painel (inclui apagar anexo enviado por outra pessoa).
403somente_leituraO espaço está em modo somente leitura.
403plano_nao_permiteO plano não inclui o recurso (ex.: link de pagamento, anexos, nota fiscal).
403limite_do_planoO limite do plano foi atingido (ex.: número de contatos). Traz "limit".
404nao_encontradoNão existe — ou não é deste espaço, ou é de um lado que a chave não vê.
404not_foundO mesmo, nas rotas /recurrences e /subscriptions.
404rota_nao_encontradaRota desconhecida.
404arquivo_indisponivelO PDF ou o XML da nota ainda não está guardado (ou não pôde ser lido agora). Veja "files".
405metodo_nao_permitidoMétodo não suportado nesta rota (as de /nfse são só GET).
405method_not_allowedO mesmo, nas rotas /recurrences e /subscriptions.
409exige_decisao_estornoConta paga online: informe "refund" (cancelar/reabrir).
409external_ref_em_usoJá existe recorrência com esta external_ref. Traz o "recurrence_id".
409exclusao_parcialContato com muitos lançamentos: chame de novo para continuar.
409nfse_ja_existeA conta já tem nota fiscal viva. Traz a nota em "nfse".
422dados_invalidosAlgum campo não passou na validação. Veja "field"/"fields" (e "reason", em /permissions/check).
422campo_invalidoO mesmo, nas rotas /recurrences. Veja "field".
422data_invalidaData fora do formato YYYY-MM-DD, ou que não existe. Veja "field".
422conta_de_itensValor ou categoria de uma conta de itens (é a soma dos itens).
422nao_foi_possivelA operação não coube no estado da conta. Veja "reason".
422item_invalidoItem de recorrência inválido. Veja "field".
422serie_sem_itensA recorrência é de valor fixo e não aceita itens.
422serie_encerradaRecorrência encerrada: não há próxima cobrança.
422sem_conta_abertaNão há cobrança aberta agora — tente mais tarde.
422so_receivablesLink de pagamento e nota fiscal só existem em conta a receber.
422conta_canceladaNão se gera link nem nota fiscal de uma conta cancelada.
422corpo_nao_aceitoPOST /receivables/{id}/nfse com corpo: a nota não recebe dados — mude a conta ou o contato.
422nfse_impedidaO espaço não pode emitir nota agora (módulo, certificado, campos). Veja "reason" e "reasons".
422provedor_sem_estornoO provedor do pagamento não aceita estorno pela API.
422estorno_falhouO estorno foi recusado; nada foi alterado. Veja "motivo".
429muitas_requisicoesLimite excedido.
500erro_internoErro 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.

Limites

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.

Webhooks

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).

A carga é só o identificador

{
  "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.

Eventos

receivable.created · receivable.updated · receivable.deleted · o mesmo para payable, contact e recurrence · e, da nota fiscal, nfse.queued · nfse.issued · nfse.failed · nfse.cancelled.

Qualquer alteração dispara updated: status, valor, dados, item de consumo, arquivo anexado ou apagado, comentário. E dispara também quando a mudança vem do painel, de um pagamento online ou da geração automática das cobranças de uma recorrência (receivable.created a cada cobrança nova) — não só pela API.

O que não dispara aviso: a passagem automática para "vencida" (compare o due_date com o dia de hoje do espaço), a correção monetária aplicada em lote e as alterações "em toda a série" feitas pelo painel (dados ou itens repetidos), que mexem em muitas contas de uma vez — ali só a parcela editada avisa. Para esses casos, sincronize com updated_since: o updated_at das contas muda normalmente.

Ao excluir um contato, os lançamentos dele perdem o vínculo (e ficam com o nome em party); chega só o contact.deleted.

Recorrências

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.

Nota fiscal

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.queuedfilaa nota entrou na fila de emissão
nfse.issuedemitidao governo emitiu: já tem número oficial
nfse.failederroparou com erro — o motivo está em data.error
nfse.cancelledcanceladaa 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.

Confirmando a assinatura

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)

Reentrega

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.