Saltar para o conteúdo
RemindCash

Cobranças

Listar, ler, criar e atualizar cobranças em rascunho, com o objeto da cobrança e todos os campos aceites.

Estado da API pública

A API v1 usa chaves bearer da empresa e exige um período de plano ativo. Os endpoints de rascunhos e de comunicação de pagamentos não enviam mensagens a clientes. Os exemplos usam marcadores — nunca cole uma chave real em código partilhado.

Endpoints

Método Caminho Permissão
GET /v1/receivables receivables:read
GET /v1/receivables/{id} receivables:read
POST /v1/receivables receivables:write
PATCH /v1/receivables/{id} receivables:write

Os pagamentos e as mudanças de estado são descritos em Acompanhamento de pagamentos.

O objeto da cobrança

Campo Tipo Descrição
id integer ID da cobrança dentro da sua empresa.
customer_id integer O cliente a que esta cobrança pertence.
amount_minor integer Montante em dívida, em unidades menores.
paid_minor integer Total registado como pago, em unidades menores.
currency string EUR, GBP, TRY ou USD.
due_date string Data de vencimento local, YYYY-MM-DD.
status string Veja os estados.
external_reference string ou null A sua própria referência, única dentro da sua empresa.
description string ou null Texto livre, até 2000 caracteres.
version string Impressão digital usada para atualizações seguras.

Listar cobranças

Os resultados são ordenados por id e paginados (veja Paginação).

BASH
curl "https://api.remindcash.com/v1/receivables?per_page=25" \
  --header "Authorization: Bearer $REMINDCASH_API_KEY"
JSON
{
    "data": [
        {
            "id": 1,
            "customer_id": 1,
            "amount_minor": 125000,
            "paid_minor": 0,
            "currency": "USD",
            "due_date": "2026-10-15",
            "status": "draft",
            "external_reference": "INV-1042",
            "description": "Website redesign",
            "version": "4e6fea39ae2fab8ccb843657f081d276513739a71787c060a007b65e3acbbbc1"
        }
    ],
    "meta": { "current_page": 1, "per_page": 25, "total": 1 },
    "request_id": "762e599f-c42c-4c49-84fb-9a2f56a3f923"
}

Obter uma cobrança

BASH
curl https://api.remindcash.com/v1/receivables/1 \
  --header "Authorization: Bearer $REMINDCASH_API_KEY"

Um ID desconhecido — ou que pertença a outra empresa — devolve 404 not_found.

Criar uma cobrança em rascunho

POST /v1/receivables cria uma cobrança com o estado draft. Exige um cabeçalho Idempotency-Key e devolve 201 Created.

Campo Obrigatório Regras
customer Um de customer ou customer_id Objeto com display_name (obrigatório, máx. 160) e pelo menos um de email ou phone_e164. Opcionais: preferred_locale (en, tr, es, fr, pt, nl) e timezone IANA.
customer_id Um de customer ou customer_id Um cliente existente na sua empresa.
amount Sim String decimal positiva, até duas casas decimais.
currency Sim EUR, GBP, TRY ou USD.
due_date Sim YYYY-MM-DD.
external_reference Não Máx. 160 caracteres. Uma referência já usada na sua empresa devolve 409 conflict.
description Não Máx. 2000 caracteres.

phone_e164 tem de estar no formato E.164, por exemplo +351912345678. Campos como status ou tenant_id são rejeitados.

BASH
curl https://api.remindcash.com/v1/receivables \
  --request POST \
  --header "Authorization: Bearer $REMINDCASH_API_KEY" \
  --header "Idempotency-Key: create-inv-1042-0001" \
  --header "Content-Type: application/json" \
  --data '{
    "customer": { "display_name": "Studio North", "email": "billing@studionorth.example" },
    "amount": "1250.00",
    "currency": "USD",
    "due_date": "2026-10-15",
    "external_reference": "INV-1042"
  }'

Os novos clientes criados desta forma continuam a precisar de ter o contacto verificado e a autorização registada na aplicação antes de poder ser enviado qualquer lembrete.

Atualizar uma cobrança em rascunho

PATCH /v1/receivables/{id} altera um rascunho. Envie expected_version (o version que leu por último) e pelo menos um campo a alterar: customer_id, amount, currency, due_date, external_reference ou description.

BASH
curl https://api.remindcash.com/v1/receivables/1 \
  --request PATCH \
  --header "Authorization: Bearer $REMINDCASH_API_KEY" \
  --header "Idempotency-Key: update-inv-1042-0001" \
  --header "Content-Type: application/json" \
  --data '{
    "expected_version": "4e6fea39ae2fab8ccb843657f081d276513739a71787c060a007b65e3acbbbc1",
    "due_date": "2026-10-20"
  }'

A resposta contém a cobrança atualizada e o seu novo version. A atualização devolve 409 conflict quando:

  • expected_version já não corresponde (alguém a alterou primeiro),
  • a cobrança já não é um rascunho,
  • é uma ocorrência de uma série recorrente,
  • existe um pagamento e tenta alterar o cliente, o montante ou a moeda.