Playground: Carnês

Para acessar o ambiente de testes você precisa de uma conta Gerencianet. <a href="https://gerencianet.com.br/#abrirconta" title="Cadastro ao nosso sistema, seja nosso cliente" target="_blank">Crie sua conta</a>. O Playground (também chamado de "sandbox") é um ambiente de desenvolvimento/testes no qual o integrador, independente da operação a ser realizada, pode utilizar para conhecer o mecanismo e o fluxo de pagamento em um ambiente 100% de teste e descomplicado. [Conheça mais](https://dev.gerencianet.com.br/docs/playground) sobre o Playground oferecido pela Gerencianet. Um carnê é um conjunto de transações (parcelas) geradas em lote e com forma de pagamento já definida. As parcelas de um carnê vencem mensalmente, de acordo com a data definida pelo integrador. Para mais detalhes sobre carnês, <a href="https://dev.gerencianet.com.br/docs/carnes-introducao" target="_blank">confira a seção específica</a>. [Para gerar um carnê](https://dev.gerencianet.com.br/docs/playground-carnes#carnet), você precisa informar os seguintes dados: - Itens (ou serviço) oferecido; - Data de vencimento da 1ª parcela; - Número de parcelas (repetições). A seguir, confira todos os endpoints presentes em nosso Playground, dentro da modalidade de "Carnês": <ul><li><div class=""><span class="post">POST</span> <a href="https://dev.gerencianet.com.br/docs/playground-carnes#carnet">/v1/carnet</a> <em>(cria um carnê)</em></div></li><li><div class=""><span class="get">GET</span> <a href="https://dev.gerencianet.com.br/docs/playground-carnes#carnet_id">/v1/carnet/:id</a> <em>(retorna informações de carnê existente)</em></div></li><li><div class=""><span class="put">PUT</span> <a href="https://dev.gerencianet.com.br/docs/playground-carnes#carnet_id_metadata">/v1/carnet/:id/metadata</a> <em>(incluir "notification_url" e "custom_id" em um carnê existente)</em></div></li><li><div class=""><span class="put">PUT</span> <a href="https://dev.gerencianet.com.br/docs/playground-carnes#carnet_id_parcel_parcel">/v1/carnet/:id/parcel/:parcel</a> <em>(alterar data de vencimento de parcela específica de um carnê)</em></div></li><li><div class=""><span class="put">PUT</span> <a href="https://dev.gerencianet.com.br/docs/playground-carnes#carnet_id_cancel">/v1/carnet/:id/cancel</a> <em>(cancela um determinado carnê)</em></div></li><li><div class=""><span class="put">PUT</span> <a href="https://dev.gerencianet.com.br/docs/playground-carnes#carnet_id_parcel_parcel_cancel">/v1/carnet/:id/parcel/:parcel/cancel</a> <em>(cancelamento de parcela específica de um carnê existente)</em></div></li><li><div class=""><span class="post">POST</span> <a href="https://dev.gerencianet.com.br/docs/playground-carnes#carnet_id_resend">/v1/carnet/:id/resend</a> <em>(reenvio por email um carnê)</em></div></li><li><div class=""><span class="post">POST</span> <a href="https://dev.gerencianet.com.br/docs/playground-carnes#carnet_id_parcel_parcel_resend">/v1/carnet/:id/parcel/:parcel/resend</a> <em>(reenviar por email determinada parcela de um carnê)</em></div></li><li><div class=""><span class="post">POST</span> <a href="https://dev.gerencianet.com.br/docs/playground-carnes#carnet_id_history">/v1/carnet/:id/history</a> <em>(acrescentar descrição ao histórico de um carnê)</em></div></li><li><div class=""><span class="put">PUT</span> <a href="https://dev.gerencianet.com.br/docs/playground-carnes#settlecarnetparcel">/v1/carnet/:id/parcel/:parcel/settle</a> <em>(marcar como pago [baixa manual] uma determinada parcela de carnê)</em></div></li></ul> <br> <hr> <div class="distancia_top"><a name="carnet"><span class="post">POST</span></a><strong class="text-endpoint">/v1/carnet</strong></div> Utilizado para geração de um conjunto de transações (parcelas) geradas em lote e com uma forma de pagamento já definida. As parcelas de um carnê vencem mensalmente, de acordo com a data definida pelo integrador. Um carnê possui o status <code>active</code> (ativo) até o vencimento da última parcela. Os principais atributos da geração de um carnê são: - <code>Item</code>: item que está sendo vendido; - <code>Customer</code>: dados pessoais do pagador; - <code>Expire_at</code>: vencimento da primeira parcela do carnê; e - <code>Repeats</code>: número de parcelas do carnê. Ainda cabe frisar que cada carnê gerado possui uma identificação única denominada <code>carnet_id</code>, e cada parcela desse carnê também possuem um identificador único denominado <code>charge_id</code>. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>POST /v1/carnet</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/9bb647c-post-carnet.png", "post-carnet.png", 1385, 367, "#eeefef" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para criar um carnê no Playground. Além disso, é possível observar a saída prevista e o schema de validação com todas as tags (obrigatórias e opcionais) disponíveis para este método: [block:code] { "codes": [ { "code": "{\n \"items\": [\n {\n \"name\": \"Meu Produto\",\n \"value\": 7500,\n \"amount\": 1\n }\n ],\n \"customer\": {\n \"name\": \"Gorbadoc Oldbuck\",\n \"cpf\": \"94271564656\",\n \"phone_number\": \"5144916523\"\n },\n \"expire_at\": \"2018-12-20\",\n \"configurations\": {\n \"fine\": 200,\n \"interest\": 33\n },\n \"message\": \"Este é um espaço de até 80 caracteres para informar algo a seu cliente\",\n \"repeats\": 5,\n \"split_items\": false\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200, // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n \"data\": {\n \"carnet_id\": 12345, // identificador único do carnê\n \"status\": \"up_to_date\", // carnê encontra-se em dia, não há nenhuma parcela inadimplente. Assim que o carnê é criado, ele também recebe este status up_to_date. O termo \"up_to_date\" equivale a \"em dia\"\n \"cover\": \"link_https_capa_do_carne\", // link da capa do carnê\n \"link\": \"link_https_do_carne\", // link do carnê, de acordo com as repetições\n \"pdf\": {\n \"carnet\": \"link_https_do_pdf_do_carne\", // link do PDF do carnê, de acordo com as repetições\n \"cover\": \"link_https_do_pdf_da_capa_do_carne\" // link do PDF da capa do carnê\n },\n \"charges\": [\n {\n \"charge_id\": 511813, // número identificador da primeira parcela do carnê\n \"parcel\": \"1\", // número da parcela do carnê\n \"status\": \"waiting\", // forma de pagamento selecionada, aguardando a confirmação do pagamento\n \"value\": 7500, // valor, em centavos, da primeira parcela do carnê (7500 equivale a R$ 75,00)\n \"expire_at\": \"2018-12-20\", // data de vencimento da parcela do carnê no seguinte formato: 2018-12-20 (equivale a 20/12/2018)\n \"url\": \"link_https_da_primeira_lamina\", // link da primeira parcela (lâmina) do carnê\n \"pdf\": {\n \"charge\": \"link_https_da_primeira_lamina\" // link do PDF da primeira parcela (lâmina) do carnê\n },\n \"barcode\": \"00000.00000 00000.000000 00000.000000 0 00000000000000\" // linha digitável da primeira parcela (lâmina) do carnê\n },\n {\n \"charge_id\": 511814, // número identificador da segunda parcela do carnê\n \"parcel\": \"2\", // número da parcela do carnê\n \"status\": \"waiting\", // forma de pagamento selecionada, aguardando a confirmação do pagamento\n \"value\": 7500, // valor, em centavos, da segunda parcela do carnê (7500 equivale a R$ 75,00)\n \"expire_at\": \"2019-01-20\", // data de vencimento da parcela do carnê no seguinte formato: 2019-01-20 (equivale a 20/01/2019)\n \"url\": \"link_https_da_segunda_lamina\", // link da segunda parcela (lâmina) do carnê\n \"pdf\": {\n \"charge\": \"link_https_da_segunda_lamina\" // link do PDF da segunda parcela (lâmina) do carnê\n },\n \"barcode\": \"00000.00000 00000.000000 00000.000000 0 00000000000000\" // linha digitável da segunda parcela (lâmina) do carnê\n },\n {\n \"charge_id\": 511815, // número identificador da terceira parcela do carnê\n \"parcel\": \"3\", // número da parcela do carnê\n \"status\": \"waiting\", // forma de pagamento selecionada, aguardando a confirmação do pagamento\n \"value\": 7500, // valor, em centavos, da terceira parcela do carnê (7500 equivale a R$ 75,00)\n \"expire_at\": \"2019-02-20\", // data de vencimento da parcela do carnê no seguinte formato: 2019-02-20 (equivale a 20/02/2019)\n \"url\": \"link_https_da_terceira_lamina\", // link da terceira parcela (lâmina) do carnê\n \"pdf\": {\n \"charge\": \"link_https_da_terceira_lamina\" // link do PDF da terceira parcela (lâmina) do carnê\n },\n \"barcode\": \"00000.00000 00000.000000 00000.000000 0 00000000000000\" // linha digitável da terceira parcela (lâmina) do carnê\n },\n {\n \"charge_id\": 511816, // número identificador da quarta parcela do carnê\n \"parcel\": \"4\", // número da parcela do carnê\n \"status\": \"waiting\", // forma de pagamento selecionada, aguardando a confirmação do pagamento\n \"value\": 7500, // valor, em centavos, da quarta parcela do carnê (7500 equivale a R$ 75,00)\n \"expire_at\": \"2019-03-20\", // data de vencimento da parcela do carnê no seguinte formato: 2019-03-20 (equivale a 20/03/2019)\n \"url\": \"link_https_da_quarta_lamina\", // link da quarta parcela (lâmina) do carnê\n \"pdf\": {\n \"charge\": \"link_https_da_quarta_lamina\" // link do PDF da quarta parcela (lâmina) do carnê\n },\n \"barcode\": \"00000.00000 00000.000000 00000.000000 0 00000000000000\" // linha digitável da quarta parcela (lâmina) do carnê\n },\n {\n \"charge_id\": 511817, // número identificador da quinta parcela do carnê\n \"parcel\": \"5\", // número da parcela do carnê\n \"status\": \"waiting\", // forma de pagamento selecionada, aguardando a confirmação do pagamento\n \"value\": 7500, // valor, em centavos, da quinta parcela do carnê (7500 equivale a R$ 75,00)\n \"expire_at\": \"2019-04-20\", // data de vencimento da parcela do carnê no seguinte formato: 2019-04-20 (equivale a 20/04/2019)\n \"url\": \"link_https_da_quinta_lamina\", // link da quinta parcela (lâmina) do carnê\n \"pdf\": {\n \"charge\": \"link_https_da_quinta_lamina\" // link do PDF da quinta parcela (lâmina) do carnê\n },\n \"barcode\": \"00000.00000 00000.000000 00000.000000 0 00000000000000\" // linha digitável da quinta parcela (lâmina) do carnê\n }\n ]\n }\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"id\": \"/Carnet\",\n \"type\": \"object\",\n \"properties\": {\n \"items\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"items\": {\n \"type\": \"object\",\n \"properties\": {\n \"name\": {\n \"type\": \"string\"\n },\n \"value\": {\n \"type\": \"integer\",\n \"minimum\": 0\n },\n \"amount\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"exclusiveMinimum\": false\n }\n },\n \"required\": [\n \"name\",\n \"value\"\n ]\n }\n },\n \"customer\": {\n \"type\": \"object\",\n \"id\": \"/BasicCustomer\",\n \"properties\": {\n \"name\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"minLength\": 1,\n \"maxLength\": 255,\n \"pattern\": \"^[ ]*(.+[ ]+)+.+[ ]*$\"\n },\n \"cpf\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"minLength\": 11,\n \"maxLength\": 11\n },\n \"email\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"maxLength\": 255,\n \"pattern\": \"^[A-Za-z0-9_\\\\-]+(?:[.][A-Za-z0-9_\\\\-]+)*@[A-Za-z0-9_]+(?:[-.][A-Za-z0-9_]+)*\\\\.[A-Za-z0-9_]+$\"\n },\n \"phone_number\": {\n \"type\": \"string\",\n \"pattern\": \"^[1-9]{2}9?[0-9]{8}$\"\n },\n \"birth\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"pattern\": \"^[12][0-9]{3}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$\"\n },\n \"address\": {\n \"type\": \"object\",\n \"id\": \"/AddressOptional\",\n \"properties\": {\n \"street\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"minLength\": 0,\n \"maxLength\": 200\n },\n \"number\": {\n \"type\": [\n \"string\",\n \"null\",\n \"integer\"\n ],\n \"minLength\": 0,\n \"maxLength\": 55\n },\n \"neighborhood\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"minLength\": 0,\n \"maxLength\": 255\n },\n \"zipcode\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"pattern\": \"^[0-9]{8}$\"\n },\n \"city\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"minLength\": 0,\n \"maxLength\": 50\n },\n \"complement\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"minLength\": 0,\n \"maxLength\": 45\n },\n \"state\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"pattern\": \"^(?:A[CLPM]|BA|CE|DF|ES|GO|M[ATSG]|P[RBAEI]|R[JNSOR]|S[CEP]|TO)$\"\n }\n }\n },\n \"juridical_person\": {\n \"type\": \"object\",\n \"id\": \"/JuridicalPerson\",\n \"properties\": {\n \"corporate_name\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"minLength\": 1,\n \"maxLength\": 255\n },\n \"cnpj\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"minLength\": 14,\n \"maxLength\": 14\n }\n },\n \"required\": [\n \"corporate_name\",\n \"cnpj\"\n ]\n }\n },\n \"required\": [\n \"phone_number\"\n ]\n },\n \"expire_at\": {\n \"type\": \"string\",\n \"pattern\": \"^[12][0-9]{3}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$\"\n },\n \"repeats\": {\n \"type\": \"integer\",\n \"minimum\": 1,\n \"maximum\": 12,\n \"exclusiveMinimum\": false,\n \"exclusiveMaximum\": false\n },\n \"split_items\": {\n \"type\": \"boolean\"\n },\n \"metadata\": {\n \"type\": \"object\",\n \"properties\": {\n \"custom_id\": {\n \"type\": [\n \"string\",\n \"null\"\n ]\n },\n \"notification_url\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"pattern\": \"^https?://.+\"\n }\n }\n },\n \"instructions\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"maxItems\": 4,\n \"items\": {\n \"type\": \"string\",\n \"minLength\": 1,\n \"maxLength\": 90\n }\n },\n \"configurations\": {\n \"type\": \"object\",\n \"id\": \"/Configurations\",\n \"minProperties\": 1,\n \"properties\": {\n \"fine\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 1000\n },\n \"interest\": {\n \"type\": \"integer\",\n \"minimum\": 0,\n \"maximum\": 330\n }\n }\n },\n \"message\": {\n \"type\": \"string\",\n \"pattern\": \"^[^\\n]{0,100}(\\n[^\\n]{0,100}){0,3}$\"\n },\n \"discount\": {\n \"type\": \"object\",\n \"id\": \"/Discount\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"percentage\",\n \"currency\"\n ]\n },\n \"value\": {\n \"type\": \"integer\",\n \"minimum\": 1\n }\n },\n \"required\": [\n \"type\",\n \"value\"\n ]\n },\n \"conditional_discount\": {\n \"id\": \"/ConditionalDiscount\",\n \"type\": \"object\",\n \"properties\": {\n \"type\": {\n \"type\": \"string\",\n \"enum\": [\n \"percentage\",\n \"currency\"\n ]\n },\n \"value\": {\n \"type\": \"integer\",\n \"minimum\": 1\n },\n \"until_date\": {\n \"type\": \"string\",\n \"pattern\": \"^[12][0-9]{3}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$\"\n }\n },\n \"required\": [\n \"type\",\n \"value\",\n \"until_date\"\n ]\n }\n },\n \"required\": [\n \"items\",\n \"customer\",\n \"expire_at\",\n \"repeats\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON cria um carnê, em que o nome do produto/serviço é "Meu Produto", valor R$ 75,00 e quantidade 1, com os dados do comprador, a data de vencimento da primeira parcela em 20/12/2018 e contendo 5 parcelas (em meses). Ou seja, é um carnê contendo 5 parcelas de R$ 75,00, perfazendo um valor total de R$ 375,00, com a primeira parcela de R$ 75,00 vencendo em 20/12/2018, a segunda em 20/01/2019, e assim sucessivamente. Além disso, estamos usando uma mensagem de até 80 caracteres para informar algo ao cliente, e se a lâmina for paga após o vencimento, será cobrado 2% de multa e 0,033% de juros por dia. <br> <hr> <div class="distancia_top"><a name="carnet_id"><span class="get">GET</span></a><strong class="text-endpoint">/v1/carnet/:id</strong></div> Retorna informações sobre um carnê criado. Cada transação criada via carnê possui uma única chave identificadora que a identifica. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>GET /v1/carnet/:id</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/Hl63OTvXTKOpx94PDqhn_c00f0b34a29744c9bb1e09b9918c62d2.png", "c00f0b34a29744c9bb1e09b9918c62d2.png", "1430", "123", "#11aac2", "" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para retornar informações sobre um carnê criado em Playground. Além disso, é possível observar a saída prevista disponível para este método. Lembrando que também é preciso informar o parâmetro de entrada <code>carnet_id</code> do carnê desejado: [block:code] { "codes": [ { "code": "Parâmetro de entrada: informe o \"carnet_id\" do carnê criado", "language": "text", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200, // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n \"data\": {\n \"carnet_id\": 14196, // número da ID referente ao carnê\n \"status\": \"active\", // carnê ativo\n \"repeats\": 3, // número de parcelas do carnê\n \"cover\": \"https://visualizacaosandbox.gerencianet.com.br/emissao/93084_624_DOCOR0/A4CC-93084-134363-CHOCA3\", // link HTTP da capa do carnê\n \"value\": 22500, // valor, em centavos, por exemplo: 22500 equivale a R$ 225,00\n \"custom_id\": null, // identificador próprio opcional\n \"notification_url\": null, // link URL de notificação\n \"split_items\": false, // dividir itens entre as parcelas (Boolean). Define se os itens do carnê serão divididos entre as parcelas (true), ou se o valor de cada parcela será o valor total dos itens (false)\n \"charges\": [\n {\n \"charge_id\": 184208, // número da ID referente à transação gerada\n \"status\": \"waiting\", // forma de pagamento selecionada, aguardando a confirmação do pagamento\n \"url\": \"https://visualizacaosandbox.gerencianet.com.br/emissao/93084_624_DOCOR0/A4CL-93084-134363-CHOCA3/93084-134363-CHOCA3\", // link HTTP da primeira parcela do carnê\n \"barcode\": \"00000.00000 00000.000000 00000.000000 0 00000000000000\", // código de barras do boleto da primeira parcela\n \"parcel\": 1, // número da parcela do carnê\n \"expire_at\": \"2017-08-20\", // data de vencimento da primeira parcela do carnê\n \"configurations\": {\n \"interest\": 33, // valor cobrado de juros por dia após a data de vencimento\n \"fine\": 200 // valor cobrado de multa após o vencimento\n }\n },\n {\n \"charge_id\": 184209, // número da ID referente à transação gerada\n \"status\": \"waiting\", // forma de pagamento selecionada, aguardando a confirmação do pagamento\n \"url\": \"https://visualizacaosandbox.gerencianet.com.br/emissao/93084_624_DOCOR0/A4CL-93084-134363-CHOCA3/93084-134364-XICOR1\", // link HTTP da segunda parcela do carnê\n \"barcode\": \"00000.00000 00000.000000 00000.000000 0 00000000000000\", // código de barras do boleto da segunda parcela\n \"parcel\": 2, // número da parcela do carnê\n \"expire_at\": \"2017-09-20\", // data de vencimento da segunda parcela do carnê\n \"configurations\": {\n \"interest\": 33, // valor cobrado de juros por dia após a data de vencimento\n \"fine\": 200 // valor cobrado de multa após o vencimento\n }\n },\n {\n \"charge_id\": 184210, // número da ID referente à transação gerada\n \"status\": \"waiting\", // forma de pagamento selecionada, aguardando a confirmação do pagamento\n \"url\": \"https://visualizacaosandbox.gerencianet.com.br/emissao/93084_624_DOCOR0/A4CL-93084-134363-CHOCA3/93084-134365-HIDA8\", // link HTTP da terceira parcela do carnê\n \"barcode\": \"00000.00000 00000.000000 00000.000000 0 00000000000000\", // código de barras do boleto da terceira parcela\n \"parcel\": 3, // número da parcela do carnê\n \"expire_at\": \"2017-10-20\", // data de vencimento da terceira parcela do carnê\n \"configurations\": {\n \"interest\": 33, // valor cobrado de juros por dia após a data de vencimento\n \"fine\": 200 // valor cobrado de multa após o vencimento\n }\n }\n ],\n \"created_at\": \"2017-02-08 09:21:36\",\n \"history\": [ // propriedades abaixo com todo o histórico deste carnê\n {\n \"message\": \"Carnê ativo\",\n \"created_at\": \"2017-02-08 09:21:36\"\n }\n ]\n }\n}", "language": "json", "name": "Dados de Saída" } ] } [/block] Esse JSON retorna informações de um carnê criado em Playground, conforme pode ser observado na aba "Dados de Saída". <br> <hr> <div class="distancia_top"><a name="carnet_id_metadata"><span class="put">PUT</span></a><strong class="text-endpoint">/v1/carnet/:id/metadata</strong></div> Permite incluir em um carnê informações como <code>notification_url</code> e <code>custom_id</code>. Para isso, você precisa informar o <code>carnet_id</code> do carnê existente no qual deseja incluir essas informações. Este endpoint é de **extrema importância** para atualizar sua URL de notificação atrelada ao carnê ou modificar o <code>custom_id</code> previamente associado aos carnês. - <code>notification_url</code>: é um endereço de sua URL válida que receberá as notificações de mudanças de status das transações. As confirmações, falhas ou qualquer tipo de alteração de status serão informadas à URL fornecida na geração do carnê; - <code>custom_id</code>: permite associar uma transação Gerencianet a uma ID específica de seu sistema ou aplicação, permitindo identificá-la caso você possua uma identificação específica e queira mantê-la. **Casos de uso deste endpoint:** - Integrador alterou o IP do servidor que estava associado na URL de notificação dos carnês; - Integrador atualizou a URL de notificação para os novos carnês que forem criadas, mas precisa atualizar também nos carnês anteriores que foram gerados e que estão associadas com a URL incorreta/desatualizada; - Foi instalado SSL (https) no servidor do cliente e mesmo que o cliente defina uma regra de redirecionamento 301 ou 302, será preciso definir a nova URL nos carnês que estão com a URL "antiga"; - Integrador gerou cobranças e não havia informado a URL de notificação ao enviar a requisição de criação do carnê; - Modificar ou acrescentar uma informação junto ao atributo <code>custom_id</code> associado aos carnês gerados previamente; - Dentre outros possíveis cenários. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>PUT /v1/carnet/:id/metadata</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/cJX9QumlTcOniH2o5ip7_fe22d560346c4efd88e469e4c9935f4c.png", "fe22d560346c4efd88e469e4c9935f4c.png", "1417", "398", "#d69131", "" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para alterar a URL de notificação e o custom_id de um carnê já existente no Playground. Além disso, é possível observar a saída prevista e o schema de validação com todas as tags (obrigatórias e opcionais) disponíveis para este método. Lembrando que também é preciso informar o parâmetro de entrada <code>carnet_id</code> do carnê desejado: [block:code] { "codes": [ { "code": "{\n \"notification_url\": \"htttp://www.meusite.com.br/notificacoes/\",\n \"custom_id\": \"258789877\"\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"type\": \"object\",\n \"minProperties\": 1,\n \"id\": \"/CarnetMetadataUpdate\",\n \"properties\": {\n \"notification_url\": {\n \"type\": [\n \"string\",\n \"null\"\n ],\n \"pattern\": \"^https?://.+\",\n \"minLength\": \"1\",\n \"maxLength\": \"255\"\n },\n \"custom_id\": {\n \"type\": \"string\",\n \"minLength\": \"1\",\n \"maxLength\": \"255\",\n \"pattern\": \"^[a-zA-Z0-9\\\\_\\\\-\\\\s]+$\"\n }\n }\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON permite alterar a URL de notificação e o custom_id de um determinado carnê. <br> <hr> <div class="distancia_top"><a name="carnet_id_parcel_parcel"><span class="put">PUT</span></a><strong class="text-endpoint">/v1/carnet/:id/parcel/:parcel</strong></div> Possibilita alterar a data de vencimento de uma determinada parcela de um carnê. Para tal, é necessário que você informe o <code>carnet_id</code>, a parcela que deseja e a <code>expire_at</code> (nova data de vencimento, no formato <code>YYYY-MM-DD</code>). Somente parcelas que estejam com status <code>waiting</code> (aguardando) ou <code>unpaid</code> (não pago) podem ter suas datas de vencimento alteradas. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>PUT /v1/carnet/:id/parcel/:parcel</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/d6S3qHYuTMi6kWbemNet_0562b15bc885466b845f6200b0c9a366.png", "0562b15bc885466b845f6200b0c9a366.png", "1434", "429", "#da902e", "" ] } ] } [/block] A seguir, um JSON simples que permite alterar a data de vencimento de uma determinada parcela de um carnê. Além disso, é possível observar a saída prevista e o schema de validação com todas as tags (obrigatórias e opcionais) disponíveis para este método. Lembrando que você deve informar o <code>carnet_id</code> e o número da parcela que deseja alterar o vencimento. [block:code] { "codes": [ { "code": "{\n \"expire_at\": \"2018-12-30\"\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"id\": \"/CarnetParcelUpdate\",\n \"type\": \"object\",\n \"properties\": {\n \"expire_at\": {\n \"type\": \"string\",\n \"pattern\": \"^[12][0-9]{3}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$\"\n }\n },\n \"required\": [\n \"expire_at\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON realiza a alteração da data de vencimento de um boleto no Playground, alterando para a data 30/12/2018 o vencimento de uma determinada parcela de um carnê. <br> <hr> <div class="distancia_top"><a name="carnet_id_cancel"><span class="put">PUT</span></a><strong class="text-endpoint">/v1/carnet/:id/cancel</strong></div> Possibilita efetuar o cancelamento de um determinado carnê. Para isso, você deve informar o <code>carnet_id</code> que deseja efetuar o cancelamento. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>PUT /v1/carnet/:id/cancel</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/NUukOsrvToyK31q9V2kb_c819c30ed6e7467fa1078a02e6fac929.png", "c819c30ed6e7467fa1078a02e6fac929.png", "1434", "123", "#f7871d", "" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para cancelar um determinado carnê. Além disso, é possível observar a saída prevista e o schema de validação com todas as tags (obrigatórias e opcionais) disponíveis para este método: [block:code] { "codes": [ { "code": "Parâmetro de entrada: informe a \"carnet_id\" do carnê desejado", "language": "text", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" } ] } [/block] Esse JSON efetua o cancelamento de um determinado carnê criado em Playground. <br> <hr> <div class="distancia_top"><a name="carnet_id_parcel_parcel_cancel"><span class="put">PUT</span></a><strong class="text-endpoint">/v1/carnet/:id/parcel/:parcel/cancel</strong></div> Possibilita efetuar o cancelamento de uma parcela específica de um carnê existente. Para isso, você deve informar o <code>carnet_id</code> e o número da parcela que deseja efetuar o cancelamento. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>PUT /v1/carnet/:id/parcel/:parcel/cancel</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/2OMtigeRTVintr7cvFxC_8ef61b22e245413eb3045c54ed4a4cd9.png", "8ef61b22e245413eb3045c54ed4a4cd9.png", "1432", "153", "#f28824", "" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para cancelar uma parcela específica de um carnê existente. Além disso, é possível observar a saída prevista disponível para este método. Lembrando que também é preciso informar o parâmetro de entrada <code>carnet_id</code> e o número da parcela do carnê: [block:code] { "codes": [ { "code": "Parâmetro de entrada: informe o \"carnet_id\" e o \"número da parcela\" do carnê", "language": "text", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" } ] } [/block] Esse JSON permite cancelar uma parcela específica de um carnê existente e que foi criado em Playground. <br> <hr> <div class="distancia_top"><a name="carnet_id_resend"><span class="post">POST</span></a><strong class="text-endpoint">/v1/carnet/:id/resend</strong></div> Este método possibilita que o carnê seja reenviado para um endereço de email. É preciso que você informe o <code>carnet_id</code> do carnê desejado. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>POST /v1/carnet/:id/resend</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/045lJwItRD6KBpKUjuAA_092014167a084e37b7552fc3716028c3.png", "092014167a084e37b7552fc3716028c3.png", "1416", "394", "#4e875b", "" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para reenviar por email um determinado carnê criado em Playground. Além disso, é possível observar a saída prevista e o schema de validação com todas as tags (obrigatórias e opcionais) disponíveis para este método. Lembrando que também é preciso informar o parâmetro de entrada <code>carnet_id</code> do carnê desejado: [block:code] { "codes": [ { "code": "{\n \"email\": \"email_do_cliente@servidor.com.br\"\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"id\": \"/CarnetResend\",\n \"type\": \"object\",\n \"properties\": {\n \"email\": {\n \"type\": \"string\",\n \"maxLength\": 255,\n \"pattern\": \"^[A-Za-z0-9_\\\\-]+(?:[.][A-Za-z0-9_\\\\-]+)*@[A-Za-z0-9_]+(?:[-.][A-Za-z0-9_]+)*\\\\.[A-Za-z0-9_]+$\"\n }\n },\n \"required\": [\n \"email\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON define que o endereço "email_do_cliente@servidor.com.br" receberá uma segunda via de um determinado carnê que foi criado em Playground. <br> <hr> <div class="distancia_top"><a name="carnet_id_parcel_parcel_resend"><span class="post">POST</span></a><strong class="text-endpoint">/v1/carnet/:id/parcel/:parcel/resend</strong></div> Este método possibilita que uma determinada parcela de um carnê seja reenviado para um endereço de e-mail. Para tal, você deve informar o <code>carnet_id</code> desejado. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>POST /v1/carnet/:id/parcel/:parcel/resend</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/5VH9L8voTIOu5oUEseCR_2ab8612babbc4db4ae7e226171cb3792.png", "2ab8612babbc4db4ae7e226171cb3792.png", "1416", "427", "#ca8639", "" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para reenviar por email um determinado carnê criado em Playground. Além disso, é possível observar a saída prevista e o schema de validação com todas as tags (obrigatórias e opcionais) disponíveis para este método. Lembrando que também é preciso informar o parâmetro de entrada <code>carnet_id</code> e o número da parcela que você deseja reenviar: [block:code] { "codes": [ { "code": "{\n \"email\": \"email_do_cliente@servidor.com.br\"\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"id\": \"/CarnetParcelResend\",\n \"type\": \"object\",\n \"properties\": {\n \"email\": {\n \"type\": \"string\",\n \"maxLength\": 255,\n \"pattern\": \"^[A-Za-z0-9_\\\\-]+(?:[.][A-Za-z0-9_\\\\-]+)*@[A-Za-z0-9_]+(?:[-.][A-Za-z0-9_]+)*\\\\.[A-Za-z0-9_]+$\"\n }\n },\n \"required\": [\n \"email\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON define que o endereço "email_do_cliente@servidor.com.br" receberá uma segunda via de uma determinada parcela de um carnê que foi criado em Playground. <br> <hr> <div class="distancia_top"><a name="carnet_id_history"><span class="post">POST</span></a><strong class="text-endpoint">/v1/carnet/:id/history</strong></div> O histórico de um carnê é semelhante ao histórico de uma transação. Porém, ele reflete as ações que o carnê em si sofreu. E, da mesma forma, é possível adicionar mensagens personalizadas ao histórico de um carnê, sem que estas, contudo, influenciem no fluxo do mesmo. Para tal, você deve informar o <code>carnet_id</code> do carnê desejado. Essa descrição deve possuir no mínimo um caractere e no máximo 255 caracteres. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>POST /v1/carnet/:id/history</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/Hctr9AK2TdqJLZEdANTc_34debf18f3fb44e1a9852eec51d7a6f6.png", "34debf18f3fb44e1a9852eec51d7a6f6.png", "1434", "397", "#4f8761", "" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para acrescentar uma descrição a um determinado carnê no Playground. Além disso, é possível observar a saída prevista e o schema de validação com todas as tags (obrigatórias e opcionais) disponíveis para este método. Lembrando que também é preciso informar o parâmetro de entrada <code>carnet_id</code> do carnê desejado: [block:code] { "codes": [ { "code": "{\n \"description\": \"Camisa Polo tamanho G cor azul\"\n}", "language": "json", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200 // retorno HTTP \"200\" informando que o pedido foi bem sucedido\n}", "language": "json", "name": "Dados de Saída" }, { "code": "{\n \"type\": \"object\",\n \"id\": \"/CarnetHistory\",\n \"properties\": {\n \"description\": {\n \"type\": \"string\",\n \"maxLength\": \"255\",\n \"minLength\": \"1\"\n }\n },\n \"required\": [\n \"description\"\n ]\n}", "language": "json", "name": "Schema" } ] } [/block] Esse JSON acrescenta a descrição "Camisa Polo tamanho G cor azul" em um determinado carnê que foi criado no Playground. <br> <hr> <div class="distancia_top"><a name="settlecarnetparcel"><span class="put">PUT</span></a><strong class="text-endpoint">/v1/carnet/:id/parcel/:parcel/settle</strong></div> Permite marcar como pago (baixa manual) uma determinada parcela de um carnê. Para tal, você deverá informar o <code>carnet_id</code> e o número da parcela do carnê que deseja marcar como pago. Ou seja, se você possui um carnê de 12 parcelas cujo <code>carnet_id</code> seja <code>24744</code> e você deseja marcar a 2ª parcela como "paga", deverá passar o <code>carnet_id</code> e o número <code>2</code>. Na imagem a seguir, é possível observar a tela de nosso ambiente de testes no qual constam os recursos atrelados ao método <code>PUT /v1/carnet/:id/parcel/:parcel/settle</code> que estão disponíveis para utilização: [block:image] { "images": [ { "image": [ "https://files.readme.io/581a53b-settleCarnetParcel.png", "settleCarnetParcel.png", 1387, 176, "#f0f1f0" ] } ] } [/block] A seguir, um JSON simples que pode ser utilizado para marcar como pago uma determinada parcela de um carnê criado em Playground. Além disso, é possível observar a saída prevista disponível para este método. Lembrando que você deve informar o <code>carnet_id</code> e o número da parcela que deseja marcar como pago: [block:code] { "codes": [ { "code": "Parâmetro de entrada: informe o \"carnet_id\" e o número da parcela do carnê que deseja marcar como pago", "language": "text", "name": "Dados de Entrada" }, { "code": "{\n \"code\": 200\n}", "language": "json", "name": "Dados de Saída" } ] } [/block]

Documentação API Gerencianet - Boleto Registrado e Pagamentos Online

** Atualização TLS

Visão Geral da API

Ambiente de Testes

Instalação da API (SDK's)

Pagar com Boleto

Pagar com Cartão

Assinaturas (Recorrência)

Carnês

Link de Pagamento

Marketplace

Checkout via Lightbox

Notificações (callbacks)

Sistemas Integrados

Módulos e Plugins

Exemplos de Integrações

Vídeos sobre Integrações

Outros Recursos

Autenticação e Endpoints

Fluxos de Processos

Últimas Novidades

Dúvidas?