Margem consignável por API

Consultar a margem disponível de um CPF

Responde 404 tanto para CPF que não existe quanto para titular que bloqueou a margem ou se opôs ao uso dos dados. A indistinção é deliberada: um erro distinguível permitiria montar a lista de quem recusou oferta.

curl -X POST https://api.cocle.com.br/v1/margens/consultas \
  -H "Authorization: Bearer $COCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "11144477735",
    "finalidade": "oferta de crédito consignado"
  }'

Resposta 200 — Vínculos encontrados, com a margem de cada um.

{
  "consulta_id": "cns_01J8Z",
  "cpf_mascarado": "***.444.777-**",
  "competencia_referencia": "2026-09",
  "vinculos": [
    {
      "vinculo_id": "vnc_01J8Z",
      "municipio": {
        "codigo_ibge": "4204608",
        "nome": "Município de Exemplo"
      },
      "orgao": "Secretaria Municipal de Educação",
      "regime": "ESTATUTARIO",
      "situacao": "ATIVO",
      "elegivel": true,
      "margens": [
        {
          "bucket": "EMPRESTIMO",
          "disponivelEfetivo": 1250
        }
      ]
    }
  ],
  "billing": {
    "evento": "CONSULTA_MARGEM",
    "faturavel": true,
    "valor": 0.45
  }
}

Reservar margem por tempo determinado

Segura a margem enquanto a proposta é analisada. Envie sempre Idempotency-Key: sem ela, uma retentativa de rede vira duas reservas e consome margem em dobro do mesmo servidor.

curl -X POST https://api.cocle.com.br/v1/reservas \
  -H "Authorization: Bearer $COCLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "vinculo_id": "vnc_...",
    "consignataria_id": "...",
    "bucket": "EMPRESTIMO",
    "valor_parcela": 250.00
  }'

Resposta 201 — Reserva criada.

{
  "reserva_id": "rsv_01J8Z",
  "margem_restante": 1000,
  "status": "VIGENTE"
}

Erros próprios deste endpoint: MARGEM_INSUFICIENTE, RESERVAS_SIMULTANEAS_EXCEDIDAS

Pedir a autorização do titular

Passo obrigatório entre reservar e averbar. As condições informadas aqui são as que o servidor vê no portal dele, e são conferidas por hash na averbação — divergência de taxa, prazo ou valor faz a averbação ser recusada.

curl -X POST https://api.cocle.com.br/v1/autorizacoes \
  -H "Authorization: Bearer $COCLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "reserva_id": "...",
    "valor_financiado": 12000.00,
    "valor_parcela": 250.00,
    "qtd_parcelas": 60,
    "taxa_am": 1.65,
    "cet_aa": 21.70
  }'

Resposta 201 — Pedido registrado. O titular decide no Portal do Servidor.

{
  "autorizacao_id": "atz_01J8Z",
  "status": "PENDENTE"
}

Erros próprios deste endpoint: RESERVA_EXPIRADA, AUTORIZACAO_JA_EXISTE

Efetivar a averbação

Só passa com autorização APROVADA pelo titular e com as condições idênticas às autorizadas. A resposta traz a memória de cálculo do success fee, para conferir a cobrança no ato e não trinta dias depois.

curl -X POST https://api.cocle.com.br/v1/averbacoes \
  -H "Authorization: Bearer $COCLE_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reserva_id": "...",
    "numero_contrato": "CT-2026-0001",
    "valor_financiado": 12000.00,
    "valor_parcela": 250.00,
    "qtd_parcelas": 60,
    "taxa_am": 1.65,
    "cet_aa": 21.70
  }'

Resposta 201 — Contrato averbado. O desconto entra na próxima folha.

{
  "contrato_id": "ctr_01J8Z",
  "status": "AVERBADA",
  "parcelas": 60,
  "billing": {
    "evento": "AVERBACAO_EFETIVADA",
    "base_calculo": "VALOR_FINANCIADO",
    "valor_base": 12000,
    "aliquota": 0.01,
    "valor": 120
  }
}

Erros próprios deste endpoint: AUTORIZACAO_AUSENTE, CONDICOES_DIVERGEM_DA_AUTORIZACAO, RESERVA_EXPIRADA

Abrir a remessa de uma competência

Primeiro passo do envio da folha. A remessa é área de espera: os lotes se acumulam nela e nada vira contracheque até o fechamento. Reabrir com a mesma referência devolve a remessa que já existe em vez de criar outra — repetir a abertura depois de um timeout é o primeiro comportamento de qualquer integrador, e duas remessas com metade dos lotes cada é exatamente a meia folha que o desenho evita.

curl -X POST https://api.cocle.com.br/v1/folha/remessas \
  -H "Authorization: Bearer $COCLE_ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "competencia": "2026-03", "referencia": "folha-mensal-001" }'

Resposta 201 — Remessa aberta, pronta para receber lotes.

{
  "remessa_id": "rmf_01J8Z",
  "status": "ABERTA",
  "competencia": "2026-03",
  "max_linhas_por_lote": 1000,
  "max_lotes": 200
}

Erros próprios deste endpoint: COMPETENCIA_INVALIDA, REMESSA_JA_FECHADA

Enviar um lote de contracheques

O lote é numerado por você, a partir de 1. Reenviar o mesmo número com o mesmo conteúdo é aceito em silêncio e não soma duas vezes — é a retentativa normal de quem integra. O mesmo número com conteúdo diferente é recusado, porque aceitar calado deixaria a divergência para o fechamento, longe de quem poderia corrigi-la. Linha com erro de formato é isolada e devolvida em `problemas`; o restante do lote entra. Uma matrícula com CPF digitado errado no cadastro não pode segurar a folha dos outros 3.999.

curl -X POST https://api.cocle.com.br/v1/folha/remessas/$REMESSA/lotes \
  -H "Authorization: Bearer $COCLE_ERP_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "lote": 1, "vinculos": [ ... ] }'

Resposta 202 — Lote recebido na área de espera. Nada virou contracheque ainda.

{
  "aceitas": 1,
  "recusadas": 0,
  "problemas": [],
  "remessa": {
    "vinculos": 1,
    "lotes_recebidos": 1,
    "total_proventos": 4200,
    "total_descontos": 462
  }
}

Erros próprios deste endpoint: LOTE_DIVERGENTE, LOTE_GRANDE, LOTE_VAZIO, LOTE_INVALIDO, REMESSA_JA_FECHADA

Fechar a remessa e aplicar a folha

Avalia a remessa inteira contra a competência anterior e, se passar, aplica numa transação só. Antes de aplicar há um freio de mudança em massa. Queda de mais de 10% nos vínculos, de mais de 15% nos proventos, crescimento de mais de 50% ou mais de 5% das linhas recusadas devolvem `status: BLOQUEADA` e a folha **não** é aplicada — a remessa fica esperando uma pessoa do município liberar, com justificativa. Não é conservadorismo: uma exportação quebrada que traz 40 servidores em vez de 4.000 zera a margem de quase toda a prefeitura numa chamada HTTP. Fechar de novo uma remessa já aplicada devolve o mesmo resultado sem reaplicar.

curl -X POST https://api.cocle.com.br/v1/folha/remessas/$REMESSA/fechamento \
  -H "Authorization: Bearer $COCLE_ERP_KEY"

Resposta 200 — Remessa avaliada. Veja `status`: APLICADA ou BLOQUEADA.

{
  "status": "APLICADA",
  "avaliacao": {
    "vinculos_agora": 612,
    "vinculos_antes": 610,
    "competencia_comparada": "2026-02",
    "variacao_vinculos": 0.0033,
    "variacao_proventos": 0.0089,
    "proporcao_problemas": 0,
    "alertas": []
  }
}

Erros próprios deste endpoint: REMESSA_VAZIA, REMESSA_JA_FECHADA

Consultar a situação da remessa

Traz status, totais, a lista de problemas linha a linha e a avaliação do freio. É o endereço para descobrir por que a folha não entrou às duas da manhã, sem abrir chamado.

curl https://api.cocle.com.br/v1/folha/remessas/$REMESSA \
  -H "Authorization: Bearer $COCLE_ERP_KEY"

Resposta 200 — Situação da remessa.

{
  "remessa_id": "rmf_01J8Z",
  "status": "APLICADA",
  "competencia": "2026-03",
  "referencia": "folha-mensal-001",
  "vinculos": 612,
  "itens": 4284,
  "lotes_recebidos": 1,
  "total_proventos": 2741320.55,
  "total_descontos": 611004.12,
  "problemas": [],
  "avaliacao": null,
  "motivo": null
}