Para software houses que revendem o ZP Cobrança aos seus clientes: cadastro da software house e cadastro/alteração dos cedentes (com conta bancária e convênio) da sua rede.
Autenticação em todos os exemplos: veja Autenticação. Teste no navegador pelo Swagger ou importe a coleção do Postman.
| Endpoint | Métodos | Para que serve |
|---|---|---|
cedente |
GET, POST, PUT | Cedentes da software house: criar, consultar e alterar (com conta e convênio) |
softwareHouse |
POST | Cadastro de uma nova software house no ZP |
Cedentes da software house: criar, consultar e alterar (com conta e convênio). Para software houses (rede no ZP) que cadastram os próprios clientes como cedentes. Só os perfis Rede (a rede da software house) e Filial (a filial da própria software house) usam; os demais recebem 403. O POST cria, numa transação, o cedente (com a pessoa, a filial e o acesso de terceiro do cedente), uma conta bancária e um convênio, e devolve os ids e o identificador do acesso do cedente. Não há DELETE. Os ids de banco, integrador e tipo de cobrança são fornecidos pela TX Fuel.
/v1/terceiro/cedenteConsulta um cedente com contas e convênios
Perfis: App, Rede, Estabelecimento
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id_cob_cedente |
integer | sim | Cedente da rede da software house. |
curl -s -X GET "$BASE/v1/terceiro/cedente?$AUTH&id_cob_cedente=25"
Resposta:
{
"status": "ok",
"dados_integracao": {
"id_cob_cedente": 25,
"identificador_terceiro": "<identificador do acesso do cedente>"
},
"cedente": {
"id_cob_cedente": 25,
"cpf_cnpj": "11222333000181",
"nome_razao_social": "EMPRESA EXEMPLO LTDA",
"cep": "80000000",
"logradouro": "AVENIDA EXEMPLO",
"numero": 1000,
"complemento": "SALA 1",
"bairro": "CENTRO",
"localidade": "CURITIBA",
"estado": "PR",
"celular": "41988880000",
"email": "financeiro@exemplo.com.br",
"telefone": "",
"ativo": "S"
},
"contas": [
{
"id_cob_conta": 40,
"id_cob_cedente": 25,
"id_cob_banco": 1,
"descricao": "CONTA PRINCIPAL",
"agencia": "1234",
"agencia_dv": "0",
"numero": "56789",
"numero_dv": "0",
"ativo": "S",
"convenios": [
{
"id_cob_convenio": 10,
"id_cob_conta": 40,
"descricao": "BOLETO CONTA PRINCIPAL",
"valor_minimo": 0.01,
"homologacao": "S",
"id_cob_integrador": 3,
"id_cob_tipo": 1,
"webhook_url": "https://sistema.exemplo.com.br/webhook/zp",
"webhook_header": "",
"validade": "2099-12-31",
"val1": "<parâmetro 1 do integrador>",
"val2": "<parâmetro 2 do integrador>",
"val3": "",
"...": "(val4 a val10)",
"ativo": "S"
}
]
}
]
}
Erros específicos: 400 — {"errors":{"id_cob_cedente":"Informe o ID do cedente"}}.; 404 — {"errors":{"registro":"Falha ao localizar: Cedente não localizado no escopo informado"}}: cedente de outra rede.; 403 — {"errors":{"acesso":"Negado"}}: perfil diferente de Rede/Filial de software house, acesso de cliente/pessoa, ou id informado no corpo diferente do cadastro..
/v1/terceiro/cedenteCria cedente, conta e convênio
Corpo JSON. Os ids (id_cob_cedente, id_cob_conta, id_cob_convenio, id_tx_pessoa) enviados no corpo são ignorados: sempre cria registros novos.
Perfis: App, Rede, Estabelecimento
Corpo (JSON objeto)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cedente |
object | sim | Dados do cedente. |
conta |
object | sim | Conta bancária. |
convenio |
object | sim | Convênio de cobrança da conta. |
curl -s -X POST "$BASE/v1/terceiro/cedente?$AUTH" \
-H 'Content-Type: application/json' \
-d '{"cedente": {"cpf_cnpj": "11222333000181", "nome_razao_social": "EMPRESA EXEMPLO LTDA", "cep": "80000000", "logradouro": "AVENIDA EXEMPLO", "numero": 1000, "complemento": "SALA 1", "bairro": "CENTRO", "localidade": "CURITIBA", "estado": "PR", "celular": "41988880000", "email": "financeiro@exemplo.com.br"}, "conta": {"id_cob_banco": 1, "descricao": "CONTA PRINCIPAL", "agencia": "1234", "agencia_dv": "0", "numero": "56789", "numero_dv": "0"}, "convenio": {"id_cob_integrador": 3, "id_cob_tipo": 1, "descricao": "BOLETO CONTA PRINCIPAL", "homologacao": "S", "webhook_url": "https://sistema.exemplo.com.br/webhook/zp", "parametros": {"val1": "<parâmetro 1 do integrador>", "val2": "<parâmetro 2 do integrador>"}}}'
Resposta:
{
"status": "ok",
"dados_integracao": {
"id_cob_cedente": 25,
"id_cob_conta": 40,
"id_cob_convenio": 10,
"identificador_terceiro": "<identificador do acesso do cedente>"
}
}
Erros específicos: 400 — {"errors":{"body":"Informe um objeto JSON válido"}}.; 400 — {"errors":{"exception":"JSONObject["conta"] not found."}}: falta cedente, conta ou convenio.; 400 — {"errors":{"cedente":{"email":["Valor não preenchido ou inválido"]}}}: validação (chaves cedente, estabelecimento, conta ou convenio).; 409 — {"errors":{"cedente.cpf_cnpj":"CPF/CNPJ já vinculado fora da rede da software house"}} ou {"errors":{"cadastro":"Dados já cadastrados"}}.; 403 — {"errors":{"acesso":"Negado"}}: perfil Rede com id_tx_estabelecimento, ou com id_tx_pessoa.; 403 — {"errors":{"acesso":"Negado"}}: perfil diferente de Rede/Filial de software house, acesso de cliente/pessoa, ou id informado no corpo diferente do cadastro.; 500 — {"errors":{"registro":"Falha ao registrar"}}..
/v1/terceiro/cedenteAltera cedente, contas e convênios (parcial)
Corpo JSON; só os blocos e campos enviados mudam. Tudo numa transação: se um bloco falhar, nada é gravado.
Perfis: App, Rede, Estabelecimento
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
id_cob_cedente |
integer | sim | Cedente (só na URL). |
Corpo (JSON objeto)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cedente |
object | não | Campos a alterar do cedente (cpf_cnpj não muda). |
conta |
object | não | Uma conta a alterar: id_cob_conta obrigatório + campos. |
contas |
array | não | Várias contas: cada uma com id_cob_conta, campos e opcionalmente convenios[] (cada um com id_cob_convenio). |
convenio |
object | não | Um convênio a alterar: id_cob_convenio obrigatório + campos (se vier conta, tem de ser dessa conta). |
curl -s -X PUT "$BASE/v1/terceiro/cedente?$AUTH&id_cob_cedente=25" \
-H 'Content-Type: application/json' \
-d '{"convenio": {"id_cob_convenio": 10, "homologacao": "N"}}'
Resposta:
{
"status": "ok",
"dados_integracao": {
"id_cob_cedente": 25,
"identificador_terceiro": "<identificador do acesso do cedente>"
},
"cedente": {
"id_cob_cedente": 25,
"cpf_cnpj": "11222333000181",
"nome_razao_social": "EMPRESA EXEMPLO LTDA",
"cep": "80000000",
"logradouro": "AVENIDA EXEMPLO",
"numero": 1000,
"complemento": "SALA 1",
"bairro": "CENTRO",
"localidade": "CURITIBA",
"estado": "PR",
"celular": "41988880000",
"email": "financeiro@exemplo.com.br",
"telefone": "",
"ativo": "S"
},
"contas": [
{
"id_cob_conta": 40,
"id_cob_cedente": 25,
"id_cob_banco": 1,
"descricao": "CONTA PRINCIPAL",
"agencia": "1234",
"agencia_dv": "0",
"numero": "56789",
"numero_dv": "0",
"ativo": "S",
"convenios": [
{
"id_cob_convenio": 10,
"id_cob_conta": 40,
"descricao": "BOLETO CONTA PRINCIPAL",
"valor_minimo": 0.01,
"homologacao": "S",
"id_cob_integrador": 3,
"id_cob_tipo": 1,
"webhook_url": "https://sistema.exemplo.com.br/webhook/zp",
"webhook_header": "",
"validade": "2099-12-31",
"val1": "<parâmetro 1 do integrador>",
"val2": "<parâmetro 2 do integrador>",
"val3": "",
"...": "(val4 a val10)",
"ativo": "S"
}
]
}
]
}
Erros específicos: 400 — {"errors":{"body":"Informe um objeto JSON válido"}}.; 400 — {"errors":{"id_cob_cedente":"Informe o ID do cedente somente na URL"}}.; 400 — {"errors":{"conta.id_cob_conta":"Informe o ID da conta a alterar"}} / {"errors":{"convenio.id_cob_convenio":"Informe o ID do convênio a alterar"}}.; 400 — {"errors":{"convenio":{"descricao":["Não pode ficar sem valor"]}}}: validação.; 403 — {"errors":{"acesso":"Negado"}}: conta/convênio que não é do cedente.; 404 — cedente fora da rede.; 409 — {"errors":{"cadastro":"Dados já cadastrados"}}.; 403 — {"errors":{"acesso":"Negado"}}: perfil diferente de Rede/Filial de software house, acesso de cliente/pessoa, ou id informado no corpo diferente do cadastro..
Cadastro de uma nova software house no ZP. Autocadastro de software house: a partir do CNPJ (dados buscados na base de CNPJ; precisa estar ATIVA), cria a pessoa e a rede da software house, associa o plano escolhido, cria a software house também como cedente (com filial e acesso de terceiro), cria o usuário responsável (login = CPF) e envia o e-mail de boas-vindas com o endereço da API e as credenciais. Só POST. Os parâmetros vão na query (ou no corpo como application/x-www-form-urlencoded); corpo JSON não é lido.
/v1/terceiro/softwareHouseCadastra a software house e o usuário responsável
Em qualquer erro nada é gravado. A resposta de sucesso não traz ids nem credenciais: elas vão por e-mail.
Perfis: App, Rede, Estabelecimento, Cliente, Pessoa
Parâmetros (query)
| Nome | Tipo | Obrigatório | Descrição |
|---|---|---|---|
cnpj_software_house |
string | sim | CNPJ da software house, só números. |
id_plano |
integer | sim | Plano contratado — id fornecido pela TX Fuel. |
cpf |
string | sim | CPF do responsável (vira o login), só números. |
nome |
string | sim | Nome do responsável. |
celular |
string | sim | Celular do responsável com DDD. |
email |
string | sim | E-mail do responsável (recebe as boas-vindas). |
senha_usuario |
string | sim | Senha inicial do responsável. |
curl -s -X POST "$BASE/v1/terceiro/softwareHouse?$AUTH&cnpj_software_house=11222333000181&id_plano=1&cpf=12345678909&nome=RESPONSAVEL EXEMPLO&celular=41999990000&email=responsavel@exemplo.com.br&senha_usuario=<senha>"
Resposta:
{
"status": "ok"
}
Erros específicos: 400 — {"errors":{"cadastro":"CNPJ não encontrado"}}.; 400 — {"errors":{"cadastro":"CNPJ não está ativo, Já existe um cadastro com esse CNPJ, Já existe um cadastro com esse e-mail"}} (mensagens juntas).; 400 — {"errors":{"cadastro":"Já existe um cadastro com esse CPF"}}.; 400 — {"errors":{"cadastro":": ; "}}: validação de algum registro criado.; 400 — {"errors":{"cadastro":"Falha ao gerar as credenciais de acesso à API"}}.; 400 — {"errors":{"exception":""}}: por exemplo id_plano ausente ou não numérico..