Subir archivo adjunto
Upload an evidence file and receive a URL for it. Pass that URL to POST /report/create in attachmentUrls to attach the file to a report — uploading alone does not create or modify a report.
Files uploaded with an organization API key are stored privately, and the URL you get back is a ChainPatrol URL rather than a storage link: it opens for signed-in members of your organization and for ChainPatrol staff, and for no one else. There is nothing for you to configure. Pass it to POST /report/create as before; once attached, the file is shown on the report page. Each returned entry’s visibility says which applies.
Send either the raw file bytes with a fileName query parameter, or a multipart/form-data body with up to 10 file parts. The whole request body must be 4194304 bytes or smaller.
The file extension decides how the file is stored and served, so it must be one of: .avif, .bmp, .csv, .doc, .docx, .eml, .gif, .jpeg, .jpg, .msg, .pdf, .png, .txt, .webp. Any Content-Type header you send is ignored in favour of the extension.
Not images only: .eml and .msg messages, PDFs and documents are all accepted. Images are displayed inline on the report; other files are listed as downloadable evidence.
Descripción general
Sube un archivo a ChainPatrol y recibe una URL a cambio. Pasa esa URL a Crear reporte enattachmentUrls para adjuntar el archivo como
evidencia.
Es un flujo de dos pasos, y los dos pasos son solicitudes separadas:
POST /attachment/upload: envías los bytes y recibes una URL.POST /report/create: incluyes esa URL enattachmentUrls.
attachmentUrls acepta cualquier URL de
acceso público, así que si ya alojas tu evidencia en algún lugar al que podamos acceder, sigue
pasando esos enlaces. Este endpoint existe para que no tengas que alojarla tú..eml y .msg, PDF, documentos de Word, CSV y texto plano;
consulta Tipos de archivo admitidos. Las imágenes se muestran
directamente dentro del reporte en el Dashboard (panel principal); todo lo demás aparece
como un archivo descargable que nuestro equipo de Takedown (solicitudes de baja de
contenido fraudulento) puede reenviar a un registrador o a un proveedor de hosting.Dos formas de enviar un archivo
El endpoint acepta cualquiera de los dos formatos. Elige el que te resulte más fácil con tu cliente HTTP.Cuerpo sin procesar
Envía los bytes del archivo como cuerpo de la solicitud y el nombre del archivo en el parámetro de consultafileName. Un archivo por solicitud.
Formulario multipart
Envíamultipart/form-data con una o más partes de archivo. Es lo que genera un formulario de
navegador, el selector de archivos de Postman o curl -F.
El nombre del archivo se toma del nombre de archivo de cada parte, así que aquí el parámetro de
consulta fileName se ignora. Los campos del formulario que no son archivos se ignoran, y los
nombres de las partes no importan: puedes enviarlas todas como file si quieres.
Manejo de los nombres de archivo
- La extensión determina cómo almacenamos y servimos el archivo, así que tiene que estar presente y ser una de las aceptadas. La comparación no distingue entre mayúsculas y minúsculas.
- Los componentes de directorio se eliminan:
../../secrets/evidence.emlse almacena comoevidence.eml. - Los nombres no deben contener caracteres de control y tienen una longitud máxima; el esquema de arriba indica el límite.
- Por lo demás, tu nombre se conserva tal cual. Eso importa porque es el nombre que se muestra
en el reporte, y el nombre que ve un registrador o un proveedor de hosting cuando nuestro
equipo de takedown reenvía el archivo; por eso
phishing-email.emlvale más queattachment1.eml. - No hay problema en subir dos archivos con el mismo nombre. Cada subida se almacena en su propia ruta, así que nunca se sobrescribe nada y el nombre que enviaste es el que recibes de vuelta.
Tipos de archivo admitidos
Las extensiones aceptadas se enumeran en la descripción de la solicitud de arriba, y esa lista se genera a partir de las mismas constantes que aplica el endpoint, así que siempre está al día. El tipo de contenido con el que servimos el archivo se deriva de la extensión, no del encabezadoContent-Type que envías, así que cualquier encabezado que defina tu cliente se
ignora. .svg y .html están excluidos a propósito: se renderizan como contenido activo, y los
archivos que servimos no deberían hacerlo.
Si necesitas un formato que no se acepta, escribe a
support@chainpatrol.io; una solución alternativa habitual es
enviar el archivo dentro de un contenedor admitido (una exportación a PDF o el .eml sin
procesar).
Límites
El tamaño máximo del cuerpo de la solicitud y la cantidad de archivos por solicitud se indican en el esquema de arriba. Hay dos cosas que el esquema no te dice:- El tamaño máximo se aplica a todo el cuerpo de la solicitud, así que en una solicitud multipart todas las partes comparten un mismo cupo. Para cualquier cosa más grande, divídela en varias solicitudes y adjunta las URL resultantes al mismo reporte.
- Las subidas tienen un límite de 60 solicitudes por minuto por organización, o por
clave de API en el caso de las claves que no están vinculadas a una. Si lo superas, se
devuelve un
429.
La URL devuelta
Respuestas de error
Todos los errores devuelven un cuerpo JSON con una única cadenaerror que describe qué
estuvo mal. Los códigos de estado se enumeran junto con las respuestas de arriba; hay dos cosas
que vale la pena destacar:
405no está en la lista, porque no es una respuesta dePOST. El endpoint solo admitePOST, y cualquier otro método devuelve405 Method Not Allowed.- Reintenta ante un
429o un502, no ante un400. Un4xxdistinto de429significa que hay que corregir la solicitud en sí, y reintentarla sin cambios fallará de la misma manera.
Buenas prácticas
- Primero sube, después reporta. Nada vincula el archivo con un reporte hasta que pasas la
URL a
report.create. Un archivo subido al que nunca se hace referencia simplemente queda sin usar. - Adjunta cada archivo a un reporte. Las subidas no son visibles en el dashboard por sí solas; el reporte es lo que permite revisarlas.
- Usa nombres de archivo descriptivos. El nombre acompaña al archivo en el dashboard y en los correos de takedown que enviamos.
- Envía el
.emlen lugar de una captura de pantalla de un correo cuando lo tengas. El mensaje sin procesar incluye los encabezados, que es sobre lo que actúan los registradores y los proveedores de correo.
Notas
- No hay ningún endpoint para listar, reemplazar ni eliminar una subida. Para corregir un error, sube el archivo correcto y usa esa URL en su lugar; para quitar evidencia de un reporte, escribe a support@chainpatrol.io.
- Los archivos no se analizan en busca de malware. No des por hecho que un archivo subido es seguro de abrir solo porque llegó a través de la API.
Autorizaciones
Your API key. This is required by most endpoints to access our API programatically. Reach out to us at support@chainpatrol.io to get an API key for your use.
Parámetros de consulta
Cuerpo
The raw file bytes. Name the file with ?fileName=.