> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastpaybrasil.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Enviar imagem do plano

> Envia a imagem que representa o plano de assinatura, em PNG, JPG ou JPEG.

Esta rota anexa uma imagem ao plano, como o logotipo do produto ou uma arte da oferta. Depois do envio, o endereço da imagem passa a aparecer no campo `imageUrl` do plano, pronto para ser exibido na sua vitrine de planos.

## Quando usar

| Situação | Como usar esta rota |
| - | - |
| Plano recém-criado sem imagem | Chame logo depois de [Criar plano](https://docs.fastpaybrasil.com/referencia/planos/criar.md), com o `id` devolvido |
| Troca da arte de uma campanha | Envie o novo arquivo para o mesmo plano |
| Ler a imagem atual | Use [Consultar plano](https://docs.fastpaybrasil.com/referencia/planos/consultar.md) e leia `imageUrl` |

## Antes de chamar

* Tenha uma chave secreta gerada por usuário com a permissão **atualizar assinaturas**. Nos perfis padrão, são **Owner**, **Manager** e **Operador**. Os perfis Visualizador, Desenvolvedor e Financeiro recebem `403` (veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil)).
* Tenha o `id` do plano.
* Tenha o arquivo em PNG, JPG ou JPEG.

> [!WARNING]
>
> Assinaturas não têm modo de teste: as cobranças são reais mesmo com a chave de teste. Veja como homologar em [Assinaturas: visão geral](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md).

> [!TIP]
>
> **Para o desenvolvedor:** esta é uma das poucas rotas de assinatura que **não** recebem JSON. O corpo vai como `multipart/form-data`, com o arquivo no campo `file`. Não defina o header `Content-Type` manualmente ao usar `FormData` no Node.js ou a opção `-F` do cURL: a biblioteca monta o header com o `boundary` correto.

## Parâmetros de caminho

**id** `string` *required*

Identificador único do plano. Ex.: `2RhQg9M7ZCg3X3nMb9W1kX8Q`.

## Corpo da requisição

Formato `multipart/form-data`. Campo obrigatório: `file`.

**file** `file` *required*

Arquivo de imagem (formato `binary`): PNG, JPG ou JPEG.

## Respostas

A resposta de sucesso não tem corpo. Para obter a URL da imagem, consulte o plano e leia o campo `imageUrl`.

| HTTP | Significado | Corpo |
| - | - | - |
| `204` | Imagem enviada | Sem corpo |
| `401` | Credencial inválida | `{"statusCode": 401, "message": "Unauthorized"}` |
| `403` | O usuário que gerou a chave não tem a permissão atualizar assinaturas | `{"message": "Acesso negado", "error": "Forbidden", "statusCode": 403}` |
| `404` | Plano não encontrado | `{"statusCode": 404, "message": "Subscription plan not found"}` |

> [!NOTE]
>
> **Para o negócio:** a imagem é um dado do plano, guardado junto com nome, preço e mensagem ao comprador. A forma de exibi-la (tamanho, recorte, onde aparece) fica a cargo da sua aplicação, que lê o `imageUrl`.

## Erros comuns

| Sintoma | Causa | Como resolver |
| - | - | - |
| `404` com "Subscription plan not found" | `id` errado ou de outra conta | Confira o `id` na [listagem de planos](https://docs.fastpaybrasil.com/referencia/planos/listar.md) |
| `401` | Chave ausente, inválida ou header montado errado | Monte o header com o Base64 de `sua_chave:` |
| `403` com `Acesso negado` | O usuário que gerou a chave não tem a permissão atualizar assinaturas (ex.: Visualizador, Desenvolvedor ou Financeiro) | Gere a chave com um usuário Owner ou Manager. Veja [Permissões por perfil](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md#permissões-por-perfil) |
| Requisição rejeitada ao enviar JSON ou Base64 | A rota espera `multipart/form-data` | Envie o arquivo no campo `file` de um formulário multipart |
| Resposta vazia interpretada como erro | Sucesso devolve `204` sem corpo | Trate `204` como sucesso e não tente ler JSON da resposta |

```http REST (JSON) theme={null}
POST /v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image HTTP/1.1
Host: api-global.fastpaybrasil.com
Authorization: Basic <base64 de "SUA_CHAVE_SECRETA:">
Content-Type: multipart/form-data; boundary=----FinviaBoundary

------FinviaBoundary
Content-Disposition: form-data; name="file"; filename="plano-premium.png"

<conteúdo de plano-premium.png>
------FinviaBoundary--
```

```bash cURL theme={null}
curl -X POST "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image" \
  -u "$FINVIA_API_KEY:" \
  -F "file=@./plano-premium.png"
```

```javascript Node.js theme={null}
import { readFile } from 'node:fs/promises';

const credentials = Buffer.from(`${process.env.FINVIA_API_KEY}:`).toString('base64');

const form = new FormData();
const image = await readFile('./plano-premium.png');
form.append('file', new Blob([image], { type: 'image/png' }), 'plano-premium.png');

const response = await fetch(
  'https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image',
  {
    method: 'POST',
    headers: { Authorization: `Basic ${credentials}` },
    body: form,
  },
);

if (response.status === 204) {
  // imagem enviada; consulte o plano para ler imageUrl
}
```

```python Python theme={null}
import os

import requests

files = {
    "file": open("./plano-premium.png", "rb"),
}

response = requests.request(
    "POST",
    "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image",
    auth=(os.environ["FINVIA_API_KEY"], ""),
    files=files,
    timeout=30,
)

print(response.status_code)
if response.content:
    print(response.json())
```

```php PHP theme={null}
<?php

$ch = curl_init('https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image');

curl_setopt_array($ch, [
    CURLOPT_CUSTOMREQUEST => 'POST',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_USERPWD => getenv('FINVIA_API_KEY') . ':',
    CURLOPT_POSTFIELDS => [
        'file' => new CURLFile('./plano-premium.png', null, 'plano-premium.png'),
    ],
]);

$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

echo $status, PHP_EOL;
print_r(json_decode($body, true));
```

```java Java theme={null}
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.Base64;
import java.io.ByteArrayOutputStream;
import java.nio.file.Files;
import java.nio.file.Path;

public class Exemplo {
    public static void main(String[] args) throws Exception {
        String credentials = Base64.getEncoder()
            .encodeToString((System.getenv("FINVIA_API_KEY") + ":").getBytes());

        String boundary = "FinviaBoundary";
        ByteArrayOutputStream form = new ByteArrayOutputStream();
        String[][] files = {
            {"file", "./plano-premium.png"},
        };
        for (String[] file : files) {
            Path path = Path.of(file[1]);
            form.write(("--" + boundary + "\r\n"
                + "Content-Disposition: form-data; name=\"" + file[0] + "\"; filename=\""
                + path.getFileName() + "\"\r\n"
                + "Content-Type: application/octet-stream\r\n\r\n").getBytes());
            form.write(Files.readAllBytes(path));
            form.write("\r\n".getBytes());
        }
        form.write(("--" + boundary + "--\r\n").getBytes());

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image"))
            .header("Authorization", "Basic " + credentials)
            .header("Content-Type", "multipart/form-data; boundary=" + boundary)
            .method("POST", HttpRequest.BodyPublishers.ofByteArray(form.toByteArray()))
            .build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());

        System.out.println(response.statusCode());
        System.out.println(response.body());
    }
}
```

```csharp C# theme={null}
using System.Net.Http.Headers;
using System.Text;

var apiKey = Environment.GetEnvironmentVariable("FINVIA_API_KEY");
var credentials = Convert.ToBase64String(Encoding.UTF8.GetBytes($"{apiKey}:"));

using var client = new HttpClient();
client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Basic", credentials);

using var form = new MultipartFormDataContent();
form.Add(new ByteArrayContent(File.ReadAllBytes("./plano-premium.png")), "file", "plano-premium.png");

var request = new HttpRequestMessage(HttpMethod.Post, "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image");
request.Content = form;

var response = await client.SendAsync(request);
Console.WriteLine((int)response.StatusCode);
Console.WriteLine(await response.Content.ReadAsStringAsync());
```

```go Go theme={null}
package main

import (
	"bytes"
	"fmt"
	"io"
	"mime/multipart"
	"net/http"
	"os"
	"path/filepath"
)

func main() {
	var form bytes.Buffer
	writer := multipart.NewWriter(&form)
	files := [][2]string{
		{"file", "./plano-premium.png"},
	}
	for _, file := range files {
		part, err := writer.CreateFormFile(file[0], filepath.Base(file[1]))
		if err != nil {
			panic(err)
		}
		content, err := os.ReadFile(file[1])
		if err != nil {
			panic(err)
		}
		part.Write(content)
	}
	writer.Close()

	req, err := http.NewRequest("POST", "https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image", &form)
	if err != nil {
		panic(err)
	}
	req.SetBasicAuth(os.Getenv("FINVIA_API_KEY"), "")
	req.Header.Set("Content-Type", writer.FormDataContentType())

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	body, _ := io.ReadAll(res.Body)
	fmt.Println(res.StatusCode)
	fmt.Println(string(body))
}
```

```ruby Ruby theme={null}
require "net/http"
require "uri"

uri = URI("https://api-global.fastpaybrasil.com/v1/subscription-plans/2RhQg9M7ZCg3X3nMb9W1kX8Q/image")
request = Net::HTTP::Post.new(uri)
request.basic_auth(ENV.fetch("FINVIA_API_KEY"), "")
request.set_form(
  [
    ["file", File.open("./plano-premium.png")],
  ],
  "multipart/form-data"
)

response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) do |http|
  http.request(request)
end

puts response.code
puts response.body
```

```text 204 theme={null}
(sem corpo)
```

```json 404 theme={null}
{
  "statusCode": 404,
  "message": "Subscription plan not found"
}
```

## Veja também

> [card] [Planos](https://docs.fastpaybrasil.com/guias/assinaturas/planos.md)
>
> Recorrência, trial e status do plano.

> [card] [Visão geral de assinaturas](https://docs.fastpaybrasil.com/guias/assinaturas/visao-geral.md)
>
> Fluxo completo, do cliente à cobrança recorrente.

> [card] [Ciclo de vida](https://docs.fastpaybrasil.com/guias/assinaturas/ciclo-de-vida.md)
>
> Status, renovação, retentativas e cancelamento.

> [card] [Webhooks de assinatura](https://docs.fastpaybrasil.com/guias/webhooks/assinatura.md)
>
> Eventos enviados a cada etapa da assinatura.

> [card] [Registrar cartão](https://docs.fastpaybrasil.com/referencia/cartoes/registrar.md)
>
> Guarde o cartão no cofre antes de criar a assinatura.

> [card] [Consultar plano](https://docs.fastpaybrasil.com/referencia/planos/consultar.md)
>
> Leia o `imageUrl` atualizado.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.