Pular para o conteúdo principal

Plataformas parceiras

Estas rotas são para plataformas parceiras homologadas pelo Tesselys, que vendem algo em nome da empresa cliente e precisam registrar a conexão e os pedidos de contratação no Tesselys. Se você está integrando o seu próprio sistema, provavelmente não precisa delas.

As duas rotas usam a mesma autenticação do resto da API (veja Autenticação): o parceiro recebe da empresa cliente a API Key e o Secret, e a empresa é sempre a dona da chave. Nada no corpo da requisição diz de qual empresa é a conexão.

MétodoRotaO que fazRecurso do plano
POST/external/v1/integrations/:provider/connectRegistra o aperto de mão do parceiroWebhooks e Integrações
DELETE/external/v1/integrations/:provider/connectDesfaz o aperto de mãoWebhooks e Integrações
POST/external/v1/hiring-requestsRecebe um pedido de contrataçãoContratos Recorrentes

Aperto de mão​

POST /external/v1/integrations/:provider/connect​

O parceiro se apresenta informando a URL dele e o segredo com que o Tesselys vai assinar as chamadas de volta. :provider é o identificador do parceiro, em minúsculas, informado pelo Tesselys na homologação. Provedor sem aperto de mão responde 404.

CampoTipoObrigatórioDescrição
baseUrlstringSimURL base pública (HTTPS) do parceiro. Endereços internos ou privados são recusados (400).
webhookSecretstringSimSegredo gerado pelo parceiro para esta conta, de 32 a 512 caracteres. O Tesselys assina com ele (HMAC-SHA256) o corpo de toda chamada de volta. Nunca é devolvido. Menos de 32 caracteres responde 400.
accountRefstringNãoIdentificador da conta no parceiro (até 120 caracteres).
accountNamestringNãoNome da conta no parceiro, exibido na tela de integrações (até 120 caracteres).
notificationEmailstringNãoE-mail que recebe o aviso quando uma chamada de volta falhar em todas as tentativas.

Resposta (200):

{
"companyKey": "acme",
"companyName": "ACME Serviços Ltda",
"provider": "NOME_DO_PROVEDOR",
"status": "DISCONNECTED",
"activatedAt": null
}
  • A conexão nasce aguardando ativação (status = DISCONNECTED): a empresa cliente precisa ativá-la no Marketplace do Tesselys.
  • Reenviar os mesmos dados não muda nada. URL ou segredo diferentes substituem os anteriores e a conexão volta a aguardar ativação.
  • Um reenvio sem accountRef, accountName ou notificationEmail mantém o valor já informado.
  • companyKey identifica a empresa em toda chamada de volta.

DELETE /external/v1/integrations/:provider/connect​

Desliga a integração do lado do Tesselys (as automações do provedor param). Use quando a chave de API da empresa for descadastrada no parceiro. Responde 200 com { "status": "DISCONNECTED" }.

Pedido de contratação​

POST /external/v1/hiring-requests​

Recebe um item contratado na plataforma parceira. O Tesselys:

  1. cria ou reaproveita o cliente e o signatário, pelo documento (CNPJ ou CPF);
  2. cria ou reaproveita o contrato do cliente, pela referência do cliente no parceiro (contract.externalRef);
  3. cria o item deste pedido no contrato.

O contrato nasce em rascunho e o item fica aguardando ativação. Nada é cobrado nem ativado nesta chamada.

A chamada é idempotente pelo item (externalSource + contractItem.externalRef): reenviar o mesmo pedido devolve os mesmos IDs com alreadyExisted: true.

Corpo:

CampoTipoObrigatórioDescrição
externalSourcestringSimSistema de origem (até 40 caracteres).
requestedByobjectNãoQuem enviou o pedido no sistema de origem: name (opcional) e email (obrigatório no bloco). O e-mail recebe o aviso se o Tesselys não conseguir devolver a ativação ou a suspensão do item.
customerobjectSimCliente (quem contrata e paga). Campos abaixo.
representativeobjectSimPessoa física que assina pelo cliente. Mesmos campos de customer, mais relation. Exige nome, CPF válido, data de nascimento e ao menos um e-mail.
contractobjectSimContrato do cliente. Campos abaixo.
contractItemobjectSimO item contratado neste pedido. Campos abaixo.

customer e representative:

CampoTipoObrigatórioDescrição
personTypestringSimCOMPANY (CNPJ) ou INDIVIDUAL (CPF). O signatário é sempre pessoa física.
namestringSimRazão social (PJ) ou nome completo (PF). É o que sai na nota fiscal.
socialNamestringNãoNome fantasia.
documentNumberstringSimCNPJ ou CPF, só dígitos. Documento inválido responde 400.
externalCodestringNãoIdentificador da pessoa no sistema de origem.
birthDatestringNão (Sim no signatário)Data de nascimento, AAAA-MM-DD.
addressMetadataobjectNãoEndereço (zipCode, street, streetNumber, complement, neighborhood, city, state, country). O código IBGE é resolvido pelo CEP.
emailsobject[]Sim (ao menos um)Lista de { "email": "...", "isMain": true }. O principal recebe nota e cobrança.
phonesobject[]NãoLista de { "phoneNumber": "41999999999", "countryCode": "55", "hasWhatsApp": true, "isMain": true }.
relationobjectNãoSó no signatário: roleType (papel junto ao cliente) e jobTitle (cargo, texto livre).

contract:

CampoTipoObrigatórioDescrição
externalRefstringSimReferência do cliente no sistema de origem. Os próximos pedidos com a mesma referência entram no mesmo contrato.
idstringNãoID de um contrato que já existe no Tesselys (cliente cadastrado fora da integração). O item entra nele, e o contrato passa a ser achado pelo externalRef nos próximos pedidos.
titlestringNãoTítulo do contrato (só na criação).
descriptionstringNãoObservações gerais (só na criação).
startDatestringNãoInício da vigência do contrato, AAAA-MM-DD (só na criação).

contractItem:

CampoTipoObrigatórioDescrição
externalRefstringSimReferência do item no sistema de origem. É a chave de idempotência.
idstringNãoID de um item que já existe no Tesselys. O pedido só vincula a referência ao item; valor, vigência e descrição não mudam.
descriptionstringSim para item novoDescrição do item.
unitPricenumberSim para item novoValor mensal do item, em reais (maior que zero).
startDatestringSim para item novoInício da vigência do item, AAAA-MM-DD.
endDatestringNãoFim da vigência, AAAA-MM-DD. Sem ele, o item vale até ser encerrado.
quantitynumberNãoQuantidade (não é número de cobranças).
metadataobjectNãoDados da origem. Pode levar billingPreference (paymentMethod, firstDueDate, notes), só informativo: não gera cobrança.

Resposta (200):

{
"customer": { "id": "…" },
"representative": { "id": "…" },
"contract": { "id": "…", "code": "CT-000123", "status": "DRAFT" },
"contractItem": { "id": "…", "activatedAt": null },
"alreadyExisted": false
}

Erros específicos:

StatusQuando
400Faltam externalSource, contract.externalRef ou contractItem.externalRef; cliente sem nome, com documento inválido ou sem e-mail; signatário incompleto; item novo sem descrição, sem valor, sem início ou com fim antes do início.
404contract.id ou contractItem.id não existe nesta empresa (ou o item já foi encerrado).
409O item ou o contrato informado já está ligado a outra referência externa, ou o cliente já tem outro contrato com a mesma referência.
422O item informado não é do contrato informado, o contrato é de outro cliente (documento diferente) ou o contrato já terminou e não recebe itens.
Ainda com dúvida?

A nossa equipe ajuda você a configurar e usar esse recurso.