Criar link de contratação para um cliente

POST

/v1/links

curl --request POST \
  --url https://sandbox-api.eagleix-corban.com.br/v1/links \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: indicacao-2026-000123' \
  --data '{ "cpf": "52998224725", "celular": "11987654321", "referenciaExterna": "example" }'

• Sandbox (só ambiente de teste)

Cria o link que o canal envia ao cliente para iniciar a contratação. A URL leva um token de uso pessoal; envie-a só ao cliente.

Idempotência: o header Idempotency-Key é opcional. Com ele, repetir a chamada com a mesma chave e os mesmos dados devolve o mesmo link (200); a mesma chave com outro CPF ou outra referência devolve 409. Sem o header, o sistema gera um UUID e cada chamada cria um link novo.

Ambiente: por enquanto, só sandbox: banco simulado, sem SMS e sem chamadas à BMG. Código OTP sempre 123456; o CPF 00000000191 é tratado como inelegível; ofertas fictícias. A produção chega em breve.

Autorizações

• canalOAuth

Parâmetros

Header Parameters

Idempotency-Key

string

Identificador único do pedido no canal (8 a 100 caracteres: letras, números e _ . : -). Se não for enviado, o sistema gera um UUID (e cada chamada cria um link novo).

Corpo da requisição^required

Tipo de mídiaapplication/json

object

cpf

required

11 dígitos, só números.

string

celular

Opcional. DDD + 9 dígitos; se informado, é sugerido para o SMS.

string

referenciaExterna

Referência do canal (por exemplo, o id do promotor que indicou).

string

<= 200 characters

Respostas

200

Replay idempotente; devolve o link criado antes.

Tipo de mídiaapplication/json

object

id

required

string format: uuid

url

Só na criação. Envie ao cliente; não registre em log.

string

status

required

string

Allowed values: CRIADO ABERTO EM_ANDAMENTO CONCLUIDO CANCELADO EXPIRADO

ambiente

required

string

Allowed values: SANDBOX REAL

cpfMascarado

required

string

referenciaExterna

string

expiraEm

required

string format: date-time

criadoEm

required

string format: date-time

abertoEm

string format: date-time

proposta

Presente quando o cliente já enviou a proposta.

object

numero

integer

status

string

criadaEm

string format: date-time

Example

{
  "status": "CRIADO",
  "ambiente": "SANDBOX",
  "cpfMascarado": "***.982.247-**"
}

201

Link criado.

Tipo de mídiaapplication/json

object

id

required

string format: uuid

url

Só na criação. Envie ao cliente; não registre em log.

string

status

required

string

Allowed values: CRIADO ABERTO EM_ANDAMENTO CONCLUIDO CANCELADO EXPIRADO

ambiente

required

string

Allowed values: SANDBOX REAL

cpfMascarado

required

string

referenciaExterna

string

expiraEm

required

string format: date-time

criadoEm

required

string format: date-time

abertoEm

string format: date-time

proposta

Presente quando o cliente já enviou a proposta.

object

numero

integer

status

string

criadaEm

string format: date-time

Example

{
  "status": "CRIADO",
  "ambiente": "SANDBOX",
  "cpfMascarado": "***.982.247-**"
}

400

Dados inválidos (cpf, celular, Idempotency-Key).

Tipo de mídiaapplication/json

object

code

required

Código estável, para tratamento programático.

string

message

required

Mensagem legível (pt-BR).

string

requestId

Id da requisição, igual ao header X-Request-Id.

string

Example

{
  "code": "unauthorized"
}

401

Token ausente, inválido ou expirado.

Tipo de mídiaapplication/json

object

code

required

Código estável, para tratamento programático.

string

message

required

Mensagem legível (pt-BR).

string

requestId

Id da requisição, igual ao header X-Request-Id.

string

Example

{
  "code": "unauthorized",
  "message": "token inválido ou expirado",
  "requestId": "8d1f0c2a9b7e4c3d2a1b0f9e"
}

Headers

WWW-Authenticate

string

Example

Bearer error="invalid_token"

403

Canal inativo ou requisição vinda de IP não autorizado.

Tipo de mídiaapplication/json

object

code

required

Código estável, para tratamento programático.

string

message

required

Mensagem legível (pt-BR).

string

requestId

Id da requisição, igual ao header X-Request-Id.

string

Example

{
  "code": "forbidden",
  "message": "canal inativo",
  "requestId": "8d1f0c2a9b7e4c3d2a1b0f9e"
}

409

Idempotency-Key já usada com outros dados.

Tipo de mídiaapplication/json

object

code

required

Código estável, para tratamento programático.

string

message

required

Mensagem legível (pt-BR).

string

requestId

Id da requisição, igual ao header X-Request-Id.

string

Example

{
  "code": "unauthorized"
}